confluence-exporter 1.0.0

package/src/utils.ts

@@ -0,0 +1,204 @@
+import { parse, stringify } from 'yaml';
+import fs, { readFileSync, existsSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { join, dirname, basename } from 'path';
+import type { ConfluenceConfig, PageIndexEntry, PageMeta } from './types.js';
+
+/**
+ * Utility functions used across the application
+ */
+
+/**
+ * Convert text to safe filename/slug
+ * 
+ * @param text - Text to slugify
+ * @returns Slugified text (lowercase, hyphens, no special chars)
+ * 
+ * @example
+ * slugify("My Page Title!") // "my-page-title"
+ */
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '') // Remove special chars
+    .replace(/\s+/g, '-')     // Replace spaces with hyphens
+    .replace(/-+/g, '-')      // Replace multiple hyphens with single
+    .trim();
+}
+
+/**
+ * Attempt to reverse slugification (best effort)
+ * Converts hyphens to spaces and capitalizes first letter of each word
+ * 
+ * @param slug - Slugified text to convert back
+ * @returns Title-cased text with spaces
+ * 
+ * @example
+ * unslugify("my-page-title") // "My Page Title"
+ */
+export function unslugify(slug: string): string {
+  return slug
+    .replace(/-/g, ' ')           // Replace hyphens with spaces
+    .replace(/\b\w/g, c => c.toUpperCase()); // Capitalize first letter of each word
+}
+
+export const pageFilename = (item: PageIndexEntry, ext='.md') => {
+  const slug = slugify(item.title);
+  return `${item.id}-${slug}${ext}`;
+};
+
+export const pagePath = (id: string, config: ConfluenceConfig) => {
+  const indexFile = join(config.outputDir, '_index.yaml');
+  const indexContent = readFileSync(indexFile, 'utf-8');
+  const index = parse(indexContent) as PageIndexEntry[];
+
+  const findParents = (id: string, path: string[]): string[] => {
+    const entry = index.find(e => e.id === id);
+    if (!entry) return [];
+    path.unshift(pageFilename(entry, ''));
+    if (entry.parentId) {
+      return findParents(entry.parentId, path);
+    }
+    return path;
+  };
+  const item = index.find(e => e.id === id);
+  if (!item) {
+    throw new Error(`Page with ID ${id} not found in index`);
+  }
+  const parents = item.parentId ? findParents(item.parentId, []) : [];
+  return join(config.outputDir, config.spaceKey, ...parents, pageFilename(item, '.html'));
+}
+
+// ============================================================================
+// Page Metadata Utilities (Index-based)
+// ============================================================================
+
+/**
+ * Read a specific entry from _index.yaml
+ */
+export function readIndexEntry(indexPath: string, pageId: string): PageIndexEntry | null {
+  if (!existsSync(indexPath)) return null;
+
+  try {
+    const content = readFileSync(indexPath, 'utf-8');
+    const index: PageIndexEntry[] = parse(content);
+    return index.find(entry => entry.id === pageId) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Update a specific entry in _index.yaml
+ */
+export function updateIndexEntry(
+  indexPath: string,
+  pageId: string,
+  updates: Partial<PageIndexEntry>
+): boolean {
+  if (!existsSync(indexPath)) return false;
+
+  try {
+    const content = readFileSync(indexPath, 'utf-8');
+    const index: PageIndexEntry[] = parse(content);
+
+    const entryIndex = index.findIndex(entry => entry.id === pageId);
+    if (entryIndex === -1) return false;
+
+    // Update the entry
+    index[entryIndex] = { ...index[entryIndex], ...updates };
+
+    // Write back to file
+    const yamlContent = stringify(index, {
+      indent: 2,
+      lineWidth: 0
+    });
+    writeFileSync(indexPath, yamlContent, 'utf-8');
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Find existing HTML file for a page by ID
+ * Searches recursively in the output directory for {pageId}-*.html pattern
+ * 
+ * @param outputDir - Root directory to search
+ * @param pageId - Page ID to find
+ * @returns Path to HTML file or null if not found
+ */
+export function findExistingFile(outputDir: string, pageId: string): string | null {
+  const pattern = new RegExp(`^${pageId}-.*\\.html$`);
+  
+  function searchDir(dir: string): string | null {
+    if (!existsSync(dir)) return null;
+    
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        
+        if (entry.isFile() && pattern.test(entry.name)) {
+          return fullPath;
+        }
+        
+        if (entry.isDirectory() && !entry.name.startsWith('_') && entry.name !== 'images') {
+          const found = searchDir(fullPath);
+          if (found) return found;
+        }
+      }
+    } catch {
+      // Ignore permission errors, etc.
+    }
+    
+    return null;
+  }
+  
+  return searchDir(outputDir);
+}
+
+/**
+ * Check if a page needs to be downloaded based on version comparison
+ * Uses index entry download tracking fields
+ * 
+ * @param indexEntry - Page entry from index with current version
+ * @returns Object with needsDownload boolean and reason
+ */
+export function checkPageStatus(
+  indexEntry: PageIndexEntry
+): { needsDownload: boolean; reason: 'new' | 'updated' | 'up-to-date'; details?: string } {
+  const downloadedVersion = indexEntry.downloadedVersion ?? 0;
+  const currentVersion = indexEntry.version ?? 0;
+
+  // If never downloaded, it's new
+  if (indexEntry.downloadedAt === undefined) {
+    return { needsDownload: true, reason: 'new' };
+  }
+
+  // Compare versions (primary check)
+  if (currentVersion > downloadedVersion) {
+    return { 
+      needsDownload: true, 
+      reason: 'updated',
+      details: `v${downloadedVersion} → v${currentVersion}`
+    };
+  }
+
+  // If versions match but downloadedVersion is 0 (fallback), compare dates
+  if (downloadedVersion === 0 && indexEntry.modifiedDate && indexEntry.downloadedAt) {
+    const currentDate = new Date(indexEntry.modifiedDate);
+    const downloadedDate = new Date(indexEntry.downloadedAt);
+    
+    if (currentDate > downloadedDate) {
+      return {
+        needsDownload: true,
+        reason: 'updated',
+        details: `modified after download`
+      };
+    }
+  }
+  
+  return { needsDownload: false, reason: 'up-to-date' };
+}

package/tests/commands/README.md

@@ -0,0 +1,123 @@
+# Command Tests
+
+This directory contains tests for all CLI commands in the Confluence to Markdown Exporter.
+
+## Test Files
+
+### `help.command.test.ts`
+Basic constructor test for the Help command.
+
+**Coverage:**
+- ✅ Instance creation
+
+### `index.command.test.ts`
+Basic constructor test for the Index command.
+
+**Coverage:**
+- ✅ Instance creation
+
+**Note:** Full API-dependent tests are not included because IndexCommand creates its own ConfluenceApi instance internally, which cannot be easily mocked with Jest + ESM modules. To fully test this command, it would need refactoring to use dependency injection.
+
+### `plan.command.test.ts`
+Basic constructor test for the Plan command.
+
+**Coverage:**
+- ✅ Instance creation
+
+**Note:** Full API-dependent tests require dependency injection refactoring.
+
+### `download.command.test.ts`
+Basic constructor test for the Download command.
+
+**Coverage:**
+- ✅ Instance creation
+
+**Note:** Full API-dependent tests require dependency injection refactoring.
+
+### `transform.command.test.ts`
+Basic constructor test for the Transform command.
+
+**Coverage:**
+- ✅ Instance creation
+
+**Note:** Full API-dependent tests require dependency injection refactoring.
+
+## Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run specific test file
+npm test -- help.command.test.ts
+
+# Run tests matching pattern
+npm test -- --testNamePattern="should transform"
+```
+
+## Test Structure
+
+All command tests follow a consistent structure:
+
+```typescript
+describe('CommandName', () => {
+  let command: CommandClass;
+  let mockContext: CommandContext;
+  
+  beforeEach(() => {
+    // Setup
+  });
+  
+  afterEach(() => {
+    // Cleanup
+  });
+  
+  describe('feature group', () => {
+    it('should do something specific', async () => {
+      // Arrange
+      // Act
+      // Assert
+    });
+  });
+});
+```
+
+## Mocking Strategy
+
+Due to ESM module constraints with Jest, most commands cannot be fully tested without refactoring:
+
+- Commands create their own `ConfluenceApi` instances internally
+- `jest.mock()` doesn't work reliably with ESM modules
+- To enable full testing, commands would need to use **dependency injection** (accepting an API instance as a parameter)
+
+## Current Test Coverage
+
+- ✅ **Command instantiation** - All 5 commands can be constructed
+- ✅ **Core transformations** - Transformer and Cleaner have full coverage
+- ⚠️ **Command execution** - Requires refactoring for dependency injection
+
+## Future Enhancements
+
+To improve test coverage:
+
+1. **Refactor commands for dependency injection**
+   - Pass `ConfluenceApi` instance to command constructors
+   - Enables easy mocking in tests
+
+2. **Add integration tests**
+   - Full workflow end-to-end testing
+   - Mock Confluence server or use recorded responses
+
+3. **Add performance tests**
+   - Large space exports
+   - Memory usage monitoring
+
+4. **Add resilience tests**
+   - API rate limiting
+   - Network timeouts and retries

package/tests/commands/download.command.test.ts

@@ -0,0 +1,8 @@
+import { DownloadCommand } from '../../src/commands/download.command.js';
+
+describe('DownloadCommand', () => {
+  it('should create an instance', () => {
+    const command = new DownloadCommand();
+    expect(command).toBeInstanceOf(DownloadCommand);
+  });
+});

package/tests/commands/help.command.test.ts

@@ -0,0 +1,8 @@
+import { HelpCommand } from '../../src/commands/help.command.js';
+
+describe('HelpCommand', () => {
+  it('should create an instance', () => {
+    const command = new HelpCommand();
+    expect(command).toBeInstanceOf(HelpCommand);
+  });
+});

package/tests/commands/index.command.test.ts

@@ -0,0 +1,8 @@
+import { IndexCommand } from '../../src/commands/index.command.js';
+
+describe('IndexCommand', () => {
+  it('should create an instance', () => {
+    const command = new IndexCommand();
+    expect(command).toBeInstanceOf(IndexCommand);
+  });
+});

package/tests/commands/plan.command.test.ts

@@ -0,0 +1,15 @@
+import { PlanCommand } from '../../src/commands/plan.command.js';
+
+describe('PlanCommand', () => {
+  it('should create an instance', () => {
+    const mockConfig = {
+      baseUrl: 'https://example.com',
+      username: 'user',
+      password: 'pass',
+      spaceKey: 'TEST',
+      outputDir: './output'
+    };
+    const command = new PlanCommand(mockConfig);
+    expect(command).toBeInstanceOf(PlanCommand);
+  });
+});

package/tests/commands/transform.command.test.ts

@@ -0,0 +1,8 @@
+import { TransformCommand } from '../../src/commands/transform.command.js';
+
+describe('TransformCommand', () => {
+  it('should create an instance', () => {
+    const command = new TransformCommand();
+    expect(command).toBeInstanceOf(TransformCommand);
+  });
+});

package/tests/fixtures/_index.yaml

@@ -0,0 +1,38 @@
+# Confluence Export Index
+# Space: TEST
+# Export Date: 2025-10-17T10:00:00.000Z
+# Page Size: 25
+
+- id: "100001"
+  title: Parent Page 1
+  version: 1
+  modifiedDate: 2025-10-01T10:00:00.000Z
+  indexedDate: 2025-10-17T10:00:00.000Z
+  pageNumber: 1
+- id: "100002"
+  title: Parent Page 2
+  version: 2
+  parentId: "100001"
+  modifiedDate: 2025-10-02T10:00:00.000Z
+  indexedDate: 2025-10-17T10:00:01.000Z
+  pageNumber: 1
+- id: "100003"
+  title: Parent Page 3
+  version: 3
+  modifiedDate: 2025-10-03T10:00:00.000Z
+  indexedDate: 2025-10-17T10:00:02.000Z
+  pageNumber: 1
+- id: "100004"
+  title: Child Page A
+  version: 1
+  parentId: "100001"
+  modifiedDate: 2025-10-04T10:00:00.000Z
+  indexedDate: 2025-10-17T10:00:03.000Z
+  pageNumber: 2
+- id: "100005"
+  title: Child Page B
+  version: 1
+  parentId: "100002"
+  modifiedDate: 2025-10-05T10:00:00.000Z
+  indexedDate: 2025-10-17T10:00:04.000Z
+  pageNumber: 2

package/tests/fixtures/mock-pages.ts

@@ -0,0 +1,62 @@
+/**
+ * Mock page data for testing
+ */
+
+import type { Page } from '../../src/types.js';
+
+export const mockRootPage: Page = {
+  id: '200001',
+  title: 'Root Page',
+  body: '<p>Root content</p>',
+  version: 1,
+  modifiedDate: '2025-10-01T10:00:00.000Z',
+};
+
+export const mockChild1: Page = {
+  id: '200002',
+  title: 'Child 1',
+  body: '<p>Child 1 content</p>',
+  version: 1,
+  parentId: '200001',
+  modifiedDate: '2025-10-02T10:00:00.000Z',
+};
+
+export const mockChild2: Page = {
+  id: '200003',
+  title: 'Child 2',
+  body: '<p>Child 2 content</p>',
+  version: 1,
+  parentId: '200001',
+  modifiedDate: '2025-10-03T10:00:00.000Z',
+};
+
+export const mockGrandchild: Page = {
+  id: '200004',
+  title: 'Grandchild',
+  body: '<p>Grandchild content</p>',
+  version: 1,
+  parentId: '200002',
+  modifiedDate: '2025-10-04T10:00:00.000Z',
+};
+
+export const mockSinglePage: Page = {
+  id: '300001',
+  title: 'Single Page',
+  body: '<p>Content</p>',
+  version: 1,
+  modifiedDate: '2025-10-01T10:00:00.000Z',
+};
+
+export const mockQueuePage: Page = {
+  id: '500002',
+  title: 'Queue Page',
+  body: '<p>Queue content</p>',
+  version: 1,
+};
+
+export const mockIndexPage: Page = {
+  id: '600001',
+  title: 'Index Page',
+  body: '<p>Index content</p>',
+  version: 1,
+};

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+  "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "allowImportingTsExtensions": false,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": false,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "sourceMap": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/cleanupRules/*": ["src/transform/cleanupRules/*"],
+      "@/cleanup": ["src/services/markdownCleanupService"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/vite.config.ts

@@ -0,0 +1,45 @@
+import { defineConfig } from 'vite';
+import { resolve } from 'path';
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: resolve(__dirname, 'src/index.ts'),
+      formats: ['es'],
+      fileName: 'index',
+    },
+    rollupOptions: {
+      external: [
+        // Node.js built-ins
+        'fs',
+        'path',
+        'url',
+        'util',
+        'stream',
+        'crypto',
+        'events',
+        'buffer',
+        'process',
+        // Dependencies
+        'dotenv',
+      ],
+    },
+    outDir: 'dist',
+    sourcemap: true,
+    target: 'node18',
+    minify: false,
+  },
+  resolve: {
+    alias: {
+      '@/cleanupRules': resolve(__dirname, './src/transform/cleanupRules'),
+      '@/cleanup': resolve(__dirname, './src/services/markdownCleanupService'),
+    },
+  },
+  // Optimize dependencies for Node.js
+  optimizeDeps: {
+    disabled: true,
+  },
+  ssr: {
+    noExternal: true,
+  },
+});