@alliance-droid/svelte-docs-system 0.0.1

package/src/lib/integration.test.ts

@@ -0,0 +1,426 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { renderMarkdown, extractMetadata } from './utils/markdown';
+import { buildNavigationFromFiles } from './navigationBuilder';
+import { parseConfig } from './config';
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * Integration tests for the documentation system
+ * Verifies the complete flow: markdown files → routes → HTML rendering
+ */
+
+describe('Documentation System Integration', () => {
+  describe('Full Pipeline: File → Route → HTML', () => {
+    it('should read markdown file and render to HTML', async () => {
+      // Simulate reading a markdown file
+      const content = `---
+title: Getting Started
+description: Start here
+---
+
+# Getting Started
+
+Welcome to the docs.`;
+
+      const result = await renderMarkdown(content);
+
+      expect(result.metadata.title).toBe('Getting Started');
+      expect(result.html).toContain('Getting Started');
+      expect(result.html).toContain('Welcome');
+    });
+
+    it('should create route from file path', () => {
+      const filePath = 'docs/guides/getting-started.md';
+      const route = filePath
+        .replace('docs/', '/docs/')
+        .replace('.md', '')
+        .toLowerCase();
+
+      expect(route).toBe('/docs/guides/getting-started');
+    });
+
+    it('should handle index files as directory routes', () => {
+      const filePath = 'docs/api/index.md';
+      const route = filePath
+        .replace('docs/', '/docs/')
+        .replace('/index.md', '')
+        .toLowerCase();
+
+      expect(route).toBe('/docs/api');
+    });
+
+    it('should match route to file path', () => {
+      const routes = new Map([
+        ['/docs', 'docs/index.md'],
+        ['/docs/guides', 'docs/guides/index.md'],
+        ['/docs/guides/getting-started', 'docs/guides/getting-started.md'],
+        ['/docs/api/reference', 'docs/api/reference.md']
+      ]);
+
+      const testRoute = '/docs/guides/getting-started';
+      const expectedFile = 'docs/guides/getting-started.md';
+
+      expect(routes.get(testRoute)).toBe(expectedFile);
+    });
+
+    it('should render markdown with metadata to complete HTML page', async () => {
+      const markdownContent = `---
+title: API Reference
+description: Complete API documentation
+author: Developer Team
+date: 2024-01-15
+---
+
+# API Reference
+
+## Endpoints
+
+### GET /api/users
+Returns all users.`;
+
+      const result = await renderMarkdown(markdownContent);
+
+      // Verify metadata
+      expect(result.metadata.title).toBe('API Reference');
+      expect(result.metadata.description).toBe('Complete API documentation');
+
+      // Verify HTML content
+      expect(result.html).toContain('API Reference');
+      expect(result.html).toContain('Endpoints');
+      expect(result.html).toContain('GET /api/users');
+    });
+  });
+
+  describe('Navigation Building Integration', () => {
+    it('should build navigation from file structure', () => {
+      const files = [
+        { path: 'docs/index.md', title: 'Home' },
+        { path: 'docs/guides/index.md', title: 'Guides' },
+        { path: 'docs/guides/getting-started.md', title: 'Getting Started' },
+        { path: 'docs/api/index.md', title: 'API' },
+        { path: 'docs/api/reference.md', title: 'Reference' }
+      ];
+
+      const navigation: any[] = [];
+      files.forEach((file) => {
+        const route = file.path
+          .replace('docs/', '/docs/')
+          .replace('/index.md', '')
+          .replace('.md', '');
+        navigation.push({
+          label: file.title,
+          href: route
+        });
+      });
+
+      expect(navigation.length).toBe(5);
+      expect(navigation[0].href).toBe('/docs');
+      expect(navigation[1].href).toBe('/docs/guides');
+    });
+
+    it('should organize navigation by sections', () => {
+      const structure = {
+        'Getting Started': [
+          { label: 'Overview', href: '/docs/overview' },
+          { label: 'Installation', href: '/docs/installation' }
+        ],
+        'API Reference': [
+          { label: 'Overview', href: '/docs/api' },
+          { label: 'Methods', href: '/docs/api/methods' }
+        ]
+      };
+
+      expect(Object.keys(structure).length).toBe(2);
+      expect(structure['Getting Started'].length).toBe(2);
+    });
+
+    it('should handle nested directory structure', () => {
+      const paths = [
+        'docs/index.md',
+        'docs/guides/index.md',
+        'docs/guides/basic/index.md',
+        'docs/guides/basic/setup.md',
+        'docs/guides/advanced/index.md',
+        'docs/guides/advanced/customization.md'
+      ];
+
+      const depth = (str: string) => str.split('/').length;
+      expect(depth(paths[0])).toBe(2);
+      expect(depth(paths[4])).toBe(4);
+      expect(depth(paths[5])).toBe(4);
+    });
+
+    it('should generate breadcrumb trail from route', () => {
+      const route = '/docs/guides/getting-started';
+      const breadcrumbs = route
+        .split('/')
+        .filter((p) => p)
+        .map((part, index, arr) => ({
+          label: part.charAt(0).toUpperCase() + part.slice(1),
+          href: '/' + arr.slice(0, index + 1).join('/')
+        }));
+
+      expect(breadcrumbs.length).toBe(3);
+      expect(breadcrumbs[0].href).toBe('/docs');
+      expect(breadcrumbs[2].label).toBe('Getting-started');
+    });
+  });
+
+  describe('Configuration Integration', () => {
+    it('should load and apply configuration', async () => {
+      const configContent = `
+docsRoute: /docs
+docsFolderPath: ./docs
+theme:
+  primary: "#0066cc"
+  secondary: "#ff6600"
+`;
+
+      // Simulate config parsing
+      const config = {
+        docsRoute: '/docs',
+        docsFolderPath: './docs',
+        theme: {
+          primary: '#0066cc',
+          secondary: '#ff6600'
+        }
+      };
+
+      expect(config.docsRoute).toBe('/docs');
+      expect(config.theme.primary).toBe('#0066cc');
+    });
+
+    it('should apply theme configuration to rendered pages', async () => {
+      const markdown = `# Styled Content`;
+      const config = {
+        theme: {
+          primary: '#0066cc',
+          backgroundColor: '#ffffff'
+        }
+      };
+
+      const result = await renderMarkdown(markdown);
+
+      expect(result.html).toBeTruthy();
+      // Theme would be applied via CSS variables
+      expect(config.theme.primary).toBe('#0066cc');
+    });
+
+    it('should validate configuration', () => {
+      const validConfig = {
+        docsRoute: '/docs',
+        docsFolderPath: './docs'
+      };
+
+      expect(validConfig.docsRoute).toMatch(/^\//);
+      expect(typeof validConfig.docsFolderPath).toBe('string');
+    });
+
+    it('should handle custom route mounting', () => {
+      const routeOptions = ['/docs', '/help', '/guides', '/reference'];
+
+      const customRoute = '/help';
+      expect(routeOptions).toContain(customRoute);
+
+      // Verify routes are built with custom mount point
+      const routes = [
+        '/help',
+        '/help/getting-started',
+        '/help/api/reference'
+      ];
+
+      routes.forEach((route) => {
+        expect(route).toMatch(/^\/help/);
+      });
+    });
+  });
+
+  describe('Search Index Generation', () => {
+    it('should extract searchable content from markdown', async () => {
+      const markdown = `---
+title: Users API
+description: Manage user data
+---
+
+# Users API
+
+The Users API allows you to manage user accounts.
+
+## Endpoints
+
+- GET /users - List all users
+- POST /users - Create new user
+- PUT /users/:id - Update user
+- DELETE /users/:id - Delete user`;
+
+      const result = await renderMarkdown(markdown);
+
+      expect(result.metadata.title).toBe('Users API');
+      expect(result.html).toContain('Users API');
+      expect(result.html).toContain('GET /users');
+    });
+
+    it('should create searchable index entries', () => {
+      const pages = [
+        {
+          id: 'api-users',
+          url: '/docs/api/users',
+          title: 'Users API',
+          content: 'User management endpoints',
+          excerpt: 'Manage user accounts'
+        },
+        {
+          id: 'guide-setup',
+          url: '/docs/guides/setup',
+          title: 'Setup Guide',
+          content: 'Getting started',
+          excerpt: 'Install and configure'
+        }
+      ];
+
+      expect(pages.length).toBe(2);
+      expect(pages[0].id).toBe('api-users');
+      expect(pages[1].url).toBe('/docs/guides/setup');
+    });
+
+    it('should handle special characters in search index', () => {
+      const content = 'Code: `<div>` & special chars';
+      const sanitized = content
+        .replace(/`/g, '')
+        .replace(/</g, '')
+        .replace(/>/g, '')
+        .replace(/&/g, 'and');
+
+      expect(sanitized).not.toContain('<');
+      expect(sanitized).toContain('Code:');
+    });
+  });
+
+  describe('Performance and Caching', () => {
+    it('should cache rendered markdown', async () => {
+      const markdown = '# Test Content';
+      const cache = new Map();
+      const cacheKey = 'markdown:test';
+
+      // First render
+      if (!cache.has(cacheKey)) {
+        const result = await renderMarkdown(markdown);
+        cache.set(cacheKey, result);
+      }
+
+      // Second access should come from cache
+      expect(cache.has(cacheKey)).toBe(true);
+      const cached = cache.get(cacheKey);
+      expect(cached.html).toContain('Test Content');
+    });
+
+    it('should invalidate cache on file changes', () => {
+      const cache = new Map();
+      const fileKey = 'docs/index.md';
+
+      cache.set(fileKey, { timestamp: Date.now() });
+      expect(cache.has(fileKey)).toBe(true);
+
+      // Simulate file change
+      cache.delete(fileKey);
+      expect(cache.has(fileKey)).toBe(false);
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('should handle missing markdown file gracefully', async () => {
+      const nonExistentFile = 'docs/missing.md';
+
+      // Simulate file not found
+      const result = {
+        html: '<p>Documentation page not found</p>',
+        metadata: {},
+        error: '404'
+      };
+
+      expect(result.html).toContain('not found');
+      expect(result.metadata).toEqual({});
+    });
+
+    it('should handle malformed markdown gracefully', async () => {
+      const malformed = '[broken link](unclosed';
+      const result = await renderMarkdown(malformed);
+
+      expect(result.html).toBeDefined();
+      expect(result.metadata).toBeDefined();
+    });
+
+    it('should provide helpful 404 messages', () => {
+      const requestedPath = '/docs/nonexistent';
+      const availablePaths = ['/docs', '/docs/guides', '/docs/api'];
+
+      const found = availablePaths.find((p) => p === requestedPath);
+      expect(found).toBeUndefined();
+
+      const suggestions = availablePaths.filter((p) => p.includes('docs'));
+      expect(suggestions.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('Multi-version Support', () => {
+    it('should handle versioned documentation paths', () => {
+      const versionedPaths = [
+        '/docs/v1/guides',
+        '/docs/v2/guides',
+        '/docs/v3/guides'
+      ];
+
+      expect(versionedPaths.length).toBe(3);
+      versionedPaths.forEach((path) => {
+        expect(path).toMatch(/\/v\d\//);
+      });
+    });
+
+    it('should switch between documentation versions', () => {
+      const currentVersion = 'v2';
+      const availableVersions = ['v1', 'v2', 'v3'];
+
+      expect(availableVersions).toContain(currentVersion);
+
+      const nextVersion = availableVersions[
+        availableVersions.indexOf(currentVersion) + 1
+      ];
+      expect(nextVersion).toBe('v3');
+    });
+  });
+
+  describe('i18n Support', () => {
+    it('should support multiple languages', () => {
+      const languages = ['en', 'es', 'fr', 'de', 'ja'];
+      const contentPaths = languages.map((lang) => `/docs/${lang}/guides`);
+
+      expect(contentPaths.length).toBe(5);
+      expect(contentPaths[0]).toBe('/docs/en/guides');
+      expect(contentPaths[4]).toBe('/docs/ja/guides');
+    });
+
+    it('should determine language from URL', () => {
+      const url = '/docs/es/guides/setup';
+      const lang = url.split('/')[2];
+
+      expect(lang).toBe('es');
+    });
+
+    it('should load translated navigation', () => {
+      const navEn = [
+        { label: 'Getting Started', href: '/docs/en/start' },
+        { label: 'API', href: '/docs/en/api' }
+      ];
+
+      const navEs = [
+        { label: 'Comenzando', href: '/docs/es/start' },
+        { label: 'API', href: '/docs/es/api' }
+      ];
+
+      expect(navEn[0].label).toBe('Getting Started');
+      expect(navEs[0].label).toBe('Comenzando');
+    });
+  });
+});