docxmlater 10.0.2 → 10.0.4

package/src/utils/ChangelogGenerator.ts

@@ -0,0 +1,1581 @@
+/**
+ * ChangelogGenerator - Generates structured changelog from Word tracked changes
+ *
+ * Converts Word revisions (w:ins, w:del, property changes) into structured
+ * changelog data with support for consolidation, categorization, and
+ * multiple output formats.
+ *
+ * Follows ECMA-376 revision semantics.
+ *
+ * @module ChangelogGenerator
+ */
+
+import type { Document } from '../core/Document';
+import { Revision, RevisionType } from '../elements/Revision';
+import { getGlobalLogger, createScopedLogger, ILogger } from './logger';
+
+// Scoped logger for ChangelogGenerator
+function getLogger(): ILogger {
+  return createScopedLogger(getGlobalLogger(), 'ChangelogGenerator');
+}
+
+/**
+ * Semantic category for grouping changes.
+ */
+export type ChangeCategory =
+  | 'content'      // Text insertions, deletions
+  | 'formatting'   // Run/paragraph property changes
+  | 'structural'   // Moves, section changes
+  | 'table'        // Table structure changes
+  | 'hyperlink'    // Hyperlink URL, text, or formatting changes
+  | 'image'        // Image insertion, deletion, or property changes
+  | 'field'        // Field insertion, deletion, or value changes
+  | 'comment'      // Comment changes
+  | 'bookmark'     // Bookmark changes
+  | 'contentControl'; // Content control (SDT) changes
+
+/**
+ * Location of a change within the document.
+ */
+export interface ChangeLocation {
+  /** Section index (0-based) */
+  sectionIndex?: number;
+  /** Paragraph index within body (0-based) */
+  paragraphIndex: number;
+  /** Run index within paragraph (0-based) */
+  runIndex?: number;
+  /** Nearest heading for context */
+  nearestHeading?: string;
+  /** Character offset within paragraph */
+  characterOffset?: number;
+}
+
+/**
+ * Represents a single change entry in the changelog.
+ * Follows ECMA-376 revision semantics.
+ */
+export interface ChangeEntry {
+  /** Unique identifier (matches revision ID) */
+  id: string;
+
+  /** ECMA-376 revision type */
+  revisionType: RevisionType;
+
+  /** Semantic category for grouping */
+  category: ChangeCategory;
+
+  /** Human-readable description */
+  description: string;
+
+  /** Author who made the change */
+  author: string;
+
+  /** ISO 8601 timestamp */
+  date: Date;
+
+  /** Location in document */
+  location: ChangeLocation;
+
+  /** Content details */
+  content: {
+    /** Text before change (for deletions/modifications) */
+    before?: string;
+    /** Text after change (for insertions/modifications) */
+    after?: string;
+    /** Affected text (for property changes) */
+    affectedText?: string;
+  };
+
+  /** Property change details (for formatting changes) */
+  propertyChange?: {
+    property: string;
+    oldValue?: string;
+    newValue?: string;
+  };
+}
+
+/**
+ * Output format for changelog generation.
+ */
+export type ChangelogFormat = 'json' | 'markdown' | 'text' | 'html' | 'csv';
+
+/**
+ * Options for changelog generation.
+ */
+export interface ChangelogOptions {
+  /** Include formatting/property changes (default: true) */
+  includeFormattingChanges?: boolean;
+  /** Consolidate similar changes (default: false) */
+  consolidate?: boolean;
+  /** Maximum context length for descriptions (default: 50) */
+  maxContextLength?: number;
+  /** Filter by authors */
+  filterAuthors?: string[];
+  /** Filter by date range */
+  filterDateRange?: { start: Date; end: Date };
+  /** Filter by categories */
+  filterCategories?: ChangeCategory[];
+  /** Output format (default: 'markdown') */
+  format?: ChangelogFormat;
+  /** Sort changes by field */
+  sortBy?: 'date' | 'author' | 'type' | 'category';
+  /** Sort order (default: 'asc') */
+  sortOrder?: 'asc' | 'desc';
+  /** Group changes by element type */
+  groupByElement?: boolean;
+  /** Include document context (nearest heading, section) */
+  includeDocumentContext?: boolean;
+}
+
+/**
+ * Consolidated change grouping similar changes together.
+ */
+export interface ConsolidatedChange {
+  /** Description of the consolidated change */
+  description: string;
+  /** Number of individual changes */
+  count: number;
+  /** Category of changes */
+  category: ChangeCategory;
+  /** Common attributes shared by all changes */
+  commonAttributes: {
+    author?: string;
+    revisionType?: RevisionType;
+    propertyChanged?: string;
+    newValue?: string;
+  };
+  /** Individual change IDs */
+  changeIds: string[];
+}
+
+/**
+ * Summary statistics for changelog entries.
+ */
+export interface ChangelogSummary {
+  /** Total number of changes */
+  total: number;
+  /** Breakdown by category */
+  byCategory: Record<ChangeCategory, number>;
+  /** Breakdown by revision type */
+  byType: Record<string, number>;
+  /** Breakdown by author */
+  byAuthor: Record<string, number>;
+  /** Date range of changes */
+  dateRange: { earliest: Date; latest: Date } | null;
+}
+
+/**
+ * Generates changelog from Word tracked changes.
+ * Follows ECMA-376 revision semantics.
+ */
+export class ChangelogGenerator {
+  /**
+   * Generate changelog entries from a document.
+   * Document must be loaded with { revisionHandling: 'preserve' }.
+   *
+   * @param doc - Document to extract revisions from
+   * @param options - Changelog generation options
+   * @returns Array of changelog entries
+   */
+  static fromDocument(doc: Document, options?: ChangelogOptions): ChangeEntry[] {
+    const revisionManager = doc.getRevisionManager();
+    if (!revisionManager) {
+      return [];
+    }
+
+    const revisions = revisionManager.getAllRevisions();
+    return this.fromRevisions(revisions, options, doc);
+  }
+
+  /**
+   * Generate changelog entries from specific revisions.
+   *
+   * @param revisions - Array of revisions to convert
+   * @param options - Changelog generation options
+   * @param doc - Optional document for context (paragraph indices, headings)
+   * @returns Array of changelog entries
+   */
+  static fromRevisions(
+    revisions: Revision[],
+    options?: ChangelogOptions,
+    doc?: Document
+  ): ChangeEntry[] {
+    const logger = getLogger();
+    const opts = {
+      includeFormattingChanges: true,
+      consolidate: false,
+      maxContextLength: 50,
+      ...options,
+    };
+
+    logger.debug('Processing revisions', {
+      total: revisions.length,
+      filters: {
+        categories: opts.filterCategories?.length ?? 0,
+        authors: opts.filterAuthors?.length ?? 0,
+        dateRange: !!opts.filterDateRange
+      }
+    });
+
+    const entries: ChangeEntry[] = [];
+    let filtered = 0;
+
+    for (let i = 0; i < revisions.length; i++) {
+      const revision = revisions[i];
+      if (!revision) continue;
+
+      const category = this.categorize(revision);
+
+      // Filter by category
+      if (opts.filterCategories && !opts.filterCategories.includes(category)) {
+        filtered++;
+        continue;
+      }
+
+      // Filter out formatting changes if requested
+      if (!opts.includeFormattingChanges && category === 'formatting') {
+        filtered++;
+        continue;
+      }
+
+      // Filter by author
+      if (opts.filterAuthors && !opts.filterAuthors.includes(revision.getAuthor())) {
+        filtered++;
+        continue;
+      }
+
+      // Filter by date range
+      if (opts.filterDateRange) {
+        const revDate = revision.getDate();
+        if (revDate < opts.filterDateRange.start || revDate > opts.filterDateRange.end) {
+          filtered++;
+          continue;
+        }
+      }
+
+      const entry = this.revisionToEntry(revision, i, opts.maxContextLength);
+      entries.push(entry);
+    }
+
+    if (filtered > 0) {
+      logger.debug('Revisions filtered', { included: entries.length, filtered });
+    }
+
+    return entries;
+  }
+
+  /**
+   * Convert a single revision to a changelog entry.
+   *
+   * @param revision - Revision to convert
+   * @param index - Index for paragraph location (default location)
+   * @param maxContextLength - Maximum length for text context
+   * @returns Changelog entry
+   */
+  private static revisionToEntry(
+    revision: Revision,
+    index: number,
+    maxContextLength: number
+  ): ChangeEntry {
+    const type = revision.getType();
+    const category = this.categorize(revision);
+    const runs = revision.getRuns();
+
+    // Extract text content from runs
+    const text = runs.map(r => r.getText()).join('');
+    const truncatedText = text.length > maxContextLength
+      ? text.substring(0, maxContextLength) + '...'
+      : text;
+
+    // Build content object based on revision type
+    const content: ChangeEntry['content'] = {};
+    if (type === 'insert' || type === 'moveTo') {
+      content.after = truncatedText;
+    } else if (type === 'delete' || type === 'moveFrom') {
+      content.before = truncatedText;
+    } else if (this.isPropertyChangeType(type)) {
+      content.affectedText = truncatedText;
+    }
+
+    // Handle hyperlink changes specially
+    const prevProps = revision.getPreviousProperties();
+    const newProps = revision.getNewProperties();
+    if (type === 'hyperlinkChange' && (prevProps || newProps)) {
+      (content as any).hyperlinkChange = {
+        urlBefore: prevProps?.url,
+        urlAfter: newProps?.url,
+        textBefore: prevProps?.text,
+        textAfter: newProps?.text,
+      };
+      // Set before/after for standard diff view
+      if (prevProps?.url !== newProps?.url) {
+        content.before = prevProps?.url;
+        content.after = newProps?.url;
+      } else if (prevProps?.text !== newProps?.text) {
+        content.before = prevProps?.text;
+        content.after = newProps?.text;
+      }
+    }
+
+    // Build property change details if applicable
+    let propertyChange: ChangeEntry['propertyChange'] | undefined;
+    if (prevProps || newProps) {
+      // Get the first property that changed
+      const allKeys = new Set([
+        ...Object.keys(prevProps || {}),
+        ...Object.keys(newProps || {}),
+      ]);
+      const firstKey = Array.from(allKeys)[0];
+      if (firstKey) {
+        propertyChange = {
+          property: firstKey,
+          oldValue: this.formatPropertyValue(prevProps?.[firstKey]),
+          newValue: this.formatPropertyValue(newProps?.[firstKey]),
+        };
+      }
+    }
+
+    // Use revision's location if available, otherwise fall back to index
+    const revisionLocation = revision.getLocation();
+    const location: ChangeLocation = {
+      paragraphIndex: revisionLocation?.paragraphIndex ?? index, // Use actual or fallback
+      sectionIndex: revisionLocation?.sectionIndex,
+      runIndex: revisionLocation?.runIndex,
+    };
+
+    return {
+      id: revision.getId().toString(),
+      revisionType: type,
+      category,
+      description: this.describeRevision(revision, maxContextLength),
+      author: revision.getAuthor(),
+      date: revision.getDate(),
+      location,
+      content,
+      propertyChange,
+    };
+  }
+
+  /**
+   * Get summary statistics for changelog entries.
+   *
+   * @param entries - Array of changelog entries
+   * @returns Summary statistics
+   */
+  static getSummary(entries: ChangeEntry[]): ChangelogSummary {
+    const byCategory: Record<ChangeCategory, number> = {
+      content: 0,
+      formatting: 0,
+      structural: 0,
+      table: 0,
+      hyperlink: 0,
+      image: 0,
+      field: 0,
+      comment: 0,
+      bookmark: 0,
+      contentControl: 0,
+    };
+    const byType: Record<string, number> = {};
+    const byAuthor: Record<string, number> = {};
+    let earliest: Date | null = null;
+    let latest: Date | null = null;
+
+    for (const entry of entries) {
+      // Count by category
+      byCategory[entry.category]++;
+
+      // Count by type
+      byType[entry.revisionType] = (byType[entry.revisionType] || 0) + 1;
+
+      // Count by author
+      byAuthor[entry.author] = (byAuthor[entry.author] || 0) + 1;
+
+      // Track date range
+      if (!earliest || entry.date < earliest) {
+        earliest = entry.date;
+      }
+      if (!latest || entry.date > latest) {
+        latest = entry.date;
+      }
+    }
+
+    return {
+      total: entries.length,
+      byCategory,
+      byType,
+      byAuthor,
+      dateRange: earliest && latest ? { earliest, latest } : null,
+    };
+  }
+
+  /**
+   * Consolidate similar changes into groups.
+   * Groups changes that share: same type, same property, same new value.
+   *
+   * @param entries - Array of changelog entries
+   * @returns Array of consolidated changes
+   */
+  static consolidate(entries: ChangeEntry[]): ConsolidatedChange[] {
+    const groups = new Map<string, ChangeEntry[]>();
+
+    for (const entry of entries) {
+      // Create grouping key
+      let key = `${entry.revisionType}_${entry.category}`;
+
+      // For property changes, include the property name and new value
+      if (entry.propertyChange) {
+        key += `_${entry.propertyChange.property}_${entry.propertyChange.newValue || ''}`;
+      }
+
+      // For content changes by same author, group them
+      key += `_${entry.author}`;
+
+      if (!groups.has(key)) {
+        groups.set(key, []);
+      }
+      groups.get(key)!.push(entry);
+    }
+
+    const consolidated: ConsolidatedChange[] = [];
+
+    for (const [_, groupEntries] of groups) {
+      const first = groupEntries[0];
+      if (!first) continue;
+
+      let description: string;
+
+      if (groupEntries.length === 1) {
+        description = first.description;
+      } else {
+        // Generate consolidated description
+        description = this.generateConsolidatedDescription(groupEntries);
+      }
+
+      consolidated.push({
+        description,
+        count: groupEntries.length,
+        category: first.category,
+        commonAttributes: {
+          author: this.allSame(groupEntries.map(e => e.author)) ? first.author : undefined,
+          revisionType: first.revisionType,
+          propertyChanged: first.propertyChange?.property,
+          newValue: first.propertyChange?.newValue,
+        },
+        changeIds: groupEntries.map(e => e.id),
+      });
+    }
+
+    // Sort by count descending
+    consolidated.sort((a, b) => b.count - a.count);
+
+    if (entries.length > 0) {
+      getLogger().info('Entries consolidated', {
+        input: entries.length,
+        groups: consolidated.length,
+        reduction: `${Math.round((1 - consolidated.length / entries.length) * 100)}%`
+      });
+    }
+
+    return consolidated;
+  }
+
+  /**
+   * Generate a consolidated description for a group of similar changes.
+   */
+  private static generateConsolidatedDescription(entries: ChangeEntry[]): string {
+    const first = entries[0];
+    if (!first) {
+      return `${entries.length} changes`;
+    }
+
+    const count = entries.length;
+
+    switch (first.revisionType) {
+      case 'insert':
+        return `Inserted text in ${count} locations`;
+      case 'delete':
+        return `Deleted text from ${count} locations`;
+      case 'moveFrom':
+      case 'moveTo':
+        return `Moved content (${count} operations)`;
+      case 'runPropertiesChange':
+        if (first.propertyChange) {
+          return `Changed ${first.propertyChange.property} to "${first.propertyChange.newValue}" (${count} times)`;
+        }
+        return `Changed run formatting (${count} times)`;
+      case 'paragraphPropertiesChange':
+        if (first.propertyChange) {
+          return `Changed paragraph ${first.propertyChange.property} (${count} times)`;
+        }
+        return `Changed paragraph formatting (${count} times)`;
+      case 'tablePropertiesChange':
+      case 'tableRowPropertiesChange':
+      case 'tableCellPropertiesChange':
+        return `Changed table formatting (${count} times)`;
+      case 'tableCellInsert':
+        return `Inserted ${count} table cells`;
+      case 'tableCellDelete':
+        return `Deleted ${count} table cells`;
+      case 'tableCellMerge':
+        return `Merged table cells (${count} operations)`;
+      case 'numberingChange':
+        return `Changed list numbering (${count} times)`;
+      case 'sectionPropertiesChange':
+        return `Changed section properties (${count} times)`;
+      default:
+        return `${count} changes of type ${first.revisionType}`;
+    }
+  }
+
+  /**
+   * Check if all values in an array are the same.
+   */
+  private static allSame<T>(arr: T[]): boolean {
+    if (arr.length === 0) return true;
+    const first = arr[0];
+    return arr.every(v => v === first);
+  }
+
+  /**
+   * Categorize a revision into a semantic category.
+   *
+   * @param revision - Revision to categorize
+   * @returns Semantic category
+   */
+  static categorize(revision: Revision): ChangeCategory {
+    const type = revision.getType();
+
+    switch (type) {
+      // Content changes
+      case 'insert':
+      case 'delete':
+        return 'content';
+
+      // Structural changes
+      case 'moveFrom':
+      case 'moveTo':
+      case 'sectionPropertiesChange':
+        return 'structural';
+
+      // Formatting changes
+      case 'runPropertiesChange':
+      case 'paragraphPropertiesChange':
+      case 'numberingChange':
+        return 'formatting';
+
+      // Table changes
+      case 'tablePropertiesChange':
+      case 'tableExceptionPropertiesChange':
+      case 'tableRowPropertiesChange':
+      case 'tableCellPropertiesChange':
+      case 'tableCellInsert':
+      case 'tableCellDelete':
+      case 'tableCellMerge':
+        return 'table';
+
+      // Hyperlink changes
+      case 'hyperlinkChange':
+        return 'hyperlink';
+
+      // Rich content changes
+      case 'imageChange':
+        return 'image';
+
+      case 'fieldChange':
+        return 'field';
+
+      case 'commentChange':
+        return 'comment';
+
+      case 'bookmarkChange':
+        return 'bookmark';
+
+      case 'contentControlChange':
+        return 'contentControl';
+
+      default:
+        return 'content';
+    }
+  }
+
+  /**
+   * Check if a revision type is a property change type.
+   */
+  private static isPropertyChangeType(type: RevisionType): boolean {
+    return [
+      'runPropertiesChange',
+      'paragraphPropertiesChange',
+      'tablePropertiesChange',
+      'tableExceptionPropertiesChange',
+      'tableRowPropertiesChange',
+      'tableCellPropertiesChange',
+      'sectionPropertiesChange',
+      'numberingChange',
+    ].includes(type);
+  }
+
+  /**
+   * Generate human-readable description for a revision.
+   *
+   * @param revision - Revision to describe
+   * @param maxLength - Maximum length for text excerpts
+   * @returns Human-readable description
+   */
+  static describeRevision(revision: Revision, maxLength = 50): string {
+    const type = revision.getType();
+    const author = revision.getAuthor();
+    const runs = revision.getRuns();
+    const text = runs.map(r => r.getText()).join('');
+    const excerpt = text.length > maxLength
+      ? `"${text.substring(0, maxLength)}..."`
+      : text ? `"${text}"` : '';
+
+    switch (type) {
+      case 'insert':
+        return excerpt ? `Inserted ${excerpt}` : 'Inserted content';
+      case 'delete':
+        return excerpt ? `Deleted ${excerpt}` : 'Deleted content';
+      case 'moveFrom':
+        return excerpt ? `Moved ${excerpt} from here` : 'Moved content from here';
+      case 'moveTo':
+        return excerpt ? `Moved ${excerpt} to here` : 'Moved content to here';
+      case 'runPropertiesChange':
+        return this.describePropertyChange(revision, 'run formatting');
+      case 'paragraphPropertiesChange':
+        return this.describePropertyChange(revision, 'paragraph formatting');
+      case 'tablePropertiesChange':
+        return 'Changed table properties';
+      case 'tableExceptionPropertiesChange':
+        return 'Changed table exception properties';
+      case 'tableRowPropertiesChange':
+        return 'Changed table row properties';
+      case 'tableCellPropertiesChange':
+        return 'Changed table cell properties';
+      case 'sectionPropertiesChange':
+        return 'Changed section properties';
+      case 'tableCellInsert':
+        return 'Inserted table cell';
+      case 'tableCellDelete':
+        return 'Deleted table cell';
+      case 'tableCellMerge':
+        return 'Merged table cells';
+      case 'numberingChange':
+        return 'Changed list numbering';
+      case 'hyperlinkChange':
+        return this.describeHyperlinkChange(revision, maxLength);
+      case 'imageChange':
+        return this.describeImageChange(revision);
+      case 'fieldChange':
+        return this.describeFieldChange(revision);
+      case 'commentChange':
+        return this.describeCommentChange(revision);
+      case 'bookmarkChange':
+        return this.describeBookmarkChange(revision);
+      case 'contentControlChange':
+        return this.describeContentControlChange(revision);
+      default:
+        return `Changed (${type})`;
+    }
+  }
+
+  /**
+   * Generate description for a hyperlink change revision.
+   */
+  private static describeHyperlinkChange(revision: Revision, maxLength: number): string {
+    const prevProps = revision.getPreviousProperties() || {};
+    const newProps = revision.getNewProperties() || {};
+    const changes: string[] = [];
+
+    if (prevProps.url !== newProps.url) {
+      changes.push('URL');
+    }
+    if (prevProps.text !== newProps.text) {
+      changes.push('display text');
+    }
+    if (prevProps.formatting !== newProps.formatting) {
+      changes.push('formatting');
+    }
+
+    if (changes.length === 0) {
+      return 'Updated hyperlink';
+    }
+
+    return `Changed hyperlink ${changes.join(' and ')}`;
+  }
+
+  /**
+   * Generate description for an image change revision.
+   */
+  private static describeImageChange(revision: Revision): string {
+    const prevProps = revision.getPreviousProperties() || {};
+    const newProps = revision.getNewProperties() || {};
+    const changes: string[] = [];
+
+    // Detect type of change
+    if (!prevProps.imageId && newProps.imageId) {
+      return `Inserted image${newProps.filename ? ` "${newProps.filename}"` : ''}`;
+    }
+    if (prevProps.imageId && !newProps.imageId) {
+      return `Deleted image${prevProps.filename ? ` "${prevProps.filename}"` : ''}`;
+    }
+
+    // Property changes
+    if (prevProps.width !== newProps.width || prevProps.height !== newProps.height) {
+      changes.push('size');
+    }
+    if (prevProps.position !== newProps.position) {
+      changes.push('position');
+    }
+    if (prevProps.wrapping !== newProps.wrapping) {
+      changes.push('wrapping');
+    }
+    if (prevProps.altText !== newProps.altText) {
+      changes.push('alt text');
+    }
+
+    if (changes.length === 0) {
+      return 'Updated image';
+    }
+
+    return `Changed image ${changes.join(' and ')}`;
+  }
+
+  /**
+   * Generate description for a field change revision.
+   */
+  private static describeFieldChange(revision: Revision): string {
+    const prevProps = revision.getPreviousProperties() || {};
+    const newProps = revision.getNewProperties() || {};
+
+    // Detect type of change
+    if (!prevProps.fieldType && newProps.fieldType) {
+      return `Inserted ${newProps.fieldType || 'field'}`;
+    }
+    if (prevProps.fieldType && !newProps.fieldType) {
+      return `Deleted ${prevProps.fieldType || 'field'}`;
+    }
+
+    // Value/formula changes
+    if (prevProps.value !== newProps.value) {
+      return `Updated ${newProps.fieldType || 'field'} value`;
+    }
+    if (prevProps.formula !== newProps.formula) {
+      return `Changed ${newProps.fieldType || 'field'} formula`;
+    }
+
+    return `Updated ${newProps.fieldType || 'field'}`;
+  }
+
+  /**
+   * Generate description for a comment change revision.
+   */
+  private static describeCommentChange(revision: Revision): string {
+    const prevProps = revision.getPreviousProperties() || {};
+    const newProps = revision.getNewProperties() || {};
+
+    // Detect type of change
+    if (!prevProps.commentId && newProps.commentId) {
+      return `Added comment${newProps.author ? ` by ${newProps.author}` : ''}`;
+    }
+    if (prevProps.commentId && !newProps.commentId) {
+      return `Deleted comment${prevProps.author ? ` by ${prevProps.author}` : ''}`;
+    }
+    if (prevProps.text !== newProps.text) {
+      return `Edited comment${newProps.author ? ` by ${newProps.author}` : ''}`;
+    }
+
+    return 'Updated comment';
+  }
+
+  /**
+   * Generate description for a bookmark change revision.
+   */
+  private static describeBookmarkChange(revision: Revision): string {
+    const prevProps = revision.getPreviousProperties() || {};
+    const newProps = revision.getNewProperties() || {};
+
+    // Detect type of change
+    if (!prevProps.bookmarkId && newProps.bookmarkId) {
+      return `Created bookmark "${newProps.name || 'unnamed'}"`;
+    }
+    if (prevProps.bookmarkId && !newProps.bookmarkId) {
+      return `Deleted bookmark "${prevProps.name || 'unnamed'}"`;
+    }
+    if (prevProps.name !== newProps.name) {
+      return `Renamed bookmark from "${prevProps.name}" to "${newProps.name}"`;
+    }
+    if (prevProps.rangeStart !== newProps.rangeStart || prevProps.rangeEnd !== newProps.rangeEnd) {
+      return `Changed bookmark "${newProps.name || 'unnamed'}" range`;
+    }
+
+    return `Updated bookmark "${newProps.name || prevProps.name || 'unnamed'}"`;
+  }
+
+  /**
+   * Generate description for a content control change revision.
+   */
+  private static describeContentControlChange(revision: Revision): string {
+    const prevProps = revision.getPreviousProperties() || {};
+    const newProps = revision.getNewProperties() || {};
+
+    // Detect type of change
+    if (!prevProps.sdtId && newProps.sdtId) {
+      return `Inserted content control${newProps.title ? ` "${newProps.title}"` : ''}`;
+    }
+    if (prevProps.sdtId && !newProps.sdtId) {
+      return `Deleted content control${prevProps.title ? ` "${prevProps.title}"` : ''}`;
+    }
+    if (prevProps.title !== newProps.title) {
+      return `Renamed content control to "${newProps.title}"`;
+    }
+    if (prevProps.content !== newProps.content) {
+      return `Changed content control${newProps.title ? ` "${newProps.title}"` : ''} content`;
+    }
+
+    return `Updated content control${newProps.title || prevProps.title ? ` "${newProps.title || prevProps.title}"` : ''}`;
+  }
+
+  /**
+   * Generate description for a property change revision.
+   */
+  private static describePropertyChange(revision: Revision, context: string): string {
+    const prevProps = revision.getPreviousProperties();
+    const newProps = revision.getNewProperties();
+
+    if (!prevProps && !newProps) {
+      return `Changed ${context}`;
+    }
+
+    // Get meaningful property names
+    const propNames: string[] = [];
+    const allKeys = new Set([
+      ...Object.keys(prevProps || {}),
+      ...Object.keys(newProps || {}),
+    ]);
+
+    for (const key of allKeys) {
+      const oldVal = prevProps?.[key];
+      const newVal = newProps?.[key];
+      if (oldVal !== newVal) {
+        propNames.push(this.friendlyPropertyName(key));
+      }
+    }
+
+    if (propNames.length === 0) {
+      return `Changed ${context}`;
+    }
+
+    if (propNames.length === 1) {
+      return `Changed ${propNames[0]}`;
+    }
+
+    if (propNames.length <= 3) {
+      return `Changed ${propNames.join(', ')}`;
+    }
+
+    return `Changed ${propNames.slice(0, 2).join(', ')} and ${propNames.length - 2} more`;
+  }
+
+  /**
+   * Format a property value for display.
+   * Handles objects, arrays, and primitives properly.
+   */
+  private static formatPropertyValue(value: unknown): string | undefined {
+    if (value === null || value === undefined) {
+      return undefined;
+    }
+    if (typeof value === 'object') {
+      try {
+        // For objects, use JSON.stringify for proper representation
+        const json = JSON.stringify(value);
+        // Truncate if too long
+        return json.length > 100 ? json.substring(0, 97) + '...' : json;
+      } catch (e) {
+        getLogger().debug('Failed to stringify value', { error: String(e) });
+        return '[complex value]';
+      }
+    }
+    // For primitives, use String() for safe conversion
+    return String(value);
+  }
+
+  /**
+   * Convert property key to friendly name.
+   */
+  private static friendlyPropertyName(key: string): string {
+    const friendlyNames: Record<string, string> = {
+      // Run (character) properties
+      b: 'bold',
+      i: 'italic',
+      u: 'underline',
+      strike: 'strikethrough',
+      dstrike: 'double strikethrough',
+      sz: 'font size',
+      szCs: 'complex script font size',
+      color: 'text color',
+      highlight: 'highlight',
+      rFonts: 'font',
+      rStyle: 'character style',
+      vertAlign: 'vertical alignment',
+      vanish: 'hidden text',
+      caps: 'all capitals',
+      smallCaps: 'small capitals',
+      outline: 'outline effect',
+      shadow: 'shadow effect',
+      emboss: 'emboss effect',
+      imprint: 'imprint effect',
+      kern: 'kerning',
+      w: 'character width',
+      spacing: 'character spacing',
+      position: 'text position',
+      shd: 'shading',
+      bdr: 'border',
+      lang: 'language',
+      eastAsianLayout: 'East Asian layout',
+      specVanish: 'special vanish',
+      oMath: 'math mode',
+
+      // Paragraph properties
+      jc: 'alignment',
+      ind: 'indentation',
+      pStyle: 'paragraph style',
+      numPr: 'list numbering',
+      pBdr: 'paragraph border',
+      tabs: 'tab stops',
+      suppressAutoHyphens: 'hyphenation',
+      kinsoku: 'kinsoku rules',
+      wordWrap: 'word wrap',
+      overflowPunct: 'overflow punctuation',
+      topLinePunct: 'top line punctuation',
+      autoSpaceDE: 'auto space (DE)',
+      autoSpaceDN: 'auto space (DN)',
+      bidi: 'bidirectional',
+      adjustRightInd: 'right indent adjustment',
+      snapToGrid: 'snap to grid',
+      contextualSpacing: 'contextual spacing',
+      mirrorIndents: 'mirror indents',
+      suppressOverlap: 'suppress overlap',
+      outlineLvl: 'outline level',
+      divId: 'HTML division',
+      keepNext: 'keep with next',
+      keepLines: 'keep lines together',
+      pageBreakBefore: 'page break before',
+      widowControl: 'widow/orphan control',
+      suppressLineNumbers: 'suppress line numbers',
+      textboxTightWrap: 'textbox tight wrap',
+
+      // Table properties
+      tblStyle: 'table style',
+      tblW: 'table width',
+      tblInd: 'table indent',
+      tblBorders: 'table borders',
+      tblCellMar: 'table cell margins',
+      tblLook: 'table look',
+      tblLayout: 'table layout',
+      gridSpan: 'column span',
+      vMerge: 'vertical merge',
+      tcW: 'cell width',
+      tcBorders: 'cell borders',
+      vAlign: 'vertical alignment',
+      textDirection: 'text direction',
+      noWrap: 'no wrap',
+      tcMar: 'cell margins',
+      tcFitText: 'fit text',
+      hideMark: 'hide mark',
+
+      // Section properties
+      sectPr: 'section properties',
+      pgSz: 'page size',
+      pgMar: 'page margins',
+      cols: 'columns',
+      docGrid: 'document grid',
+      headerReference: 'header',
+      footerReference: 'footer',
+      pgNumType: 'page numbering',
+      formProt: 'form protection',
+      titlePg: 'different first page',
+      type: 'section type',
+    };
+
+    return friendlyNames[key] || key;
+  }
+
+  /**
+   * Export changelog to Markdown format.
+   *
+   * @param entries - Array of changelog entries
+   * @param options - Export options
+   * @returns Markdown string
+   */
+  static toMarkdown(
+    entries: ChangeEntry[],
+    options?: { includeMetadata?: boolean }
+  ): string {
+    const opts = { includeMetadata: true, ...options };
+    const lines: string[] = [];
+
+    lines.push('# Document Changes');
+    lines.push('');
+
+    if (opts.includeMetadata) {
+      const summary = this.getSummary(entries);
+      lines.push(`**Total Changes:** ${summary.total}`);
+      lines.push('');
+
+      if (summary.dateRange) {
+        lines.push(`**Date Range:** ${summary.dateRange.earliest.toLocaleDateString()} - ${summary.dateRange.latest.toLocaleDateString()}`);
+        lines.push('');
+      }
+
+      const authors = Object.keys(summary.byAuthor);
+      if (authors.length > 0) {
+        lines.push(`**Authors:** ${authors.join(', ')}`);
+        lines.push('');
+      }
+
+      lines.push('---');
+      lines.push('');
+    }
+
+    // Group by category
+    const byCategory = new Map<ChangeCategory, ChangeEntry[]>();
+    for (const entry of entries) {
+      if (!byCategory.has(entry.category)) {
+        byCategory.set(entry.category, []);
+      }
+      byCategory.get(entry.category)!.push(entry);
+    }
+
+    const categoryTitles: Record<ChangeCategory, string> = {
+      content: 'Content Changes',
+      formatting: 'Formatting Changes',
+      structural: 'Structural Changes',
+      table: 'Table Changes',
+      hyperlink: 'Hyperlink Changes',
+      image: 'Image Changes',
+      field: 'Field Changes',
+      comment: 'Comment Changes',
+      bookmark: 'Bookmark Changes',
+      contentControl: 'Content Control Changes',
+    };
+
+    for (const [category, categoryEntries] of byCategory) {
+      if (categoryEntries.length === 0) continue;
+
+      lines.push(`## ${categoryTitles[category]}`);
+      lines.push('');
+
+      for (const entry of categoryEntries) {
+        const date = entry.date.toLocaleDateString();
+        lines.push(`- ${entry.description} *(${entry.author}, ${date})*`);
+
+        if (entry.content.before) {
+          lines.push(`  - Removed: "${entry.content.before}"`);
+        }
+        if (entry.content.after) {
+          lines.push(`  - Added: "${entry.content.after}"`);
+        }
+      }
+
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Export changelog to plain text format.
+   *
+   * @param entries - Array of changelog entries
+   * @returns Plain text string
+   */
+  static toPlainText(entries: ChangeEntry[]): string {
+    const lines: string[] = [];
+
+    lines.push('DOCUMENT CHANGES');
+    lines.push('================');
+    lines.push('');
+
+    for (const entry of entries) {
+      const date = entry.date.toLocaleDateString();
+      lines.push(`[${date}] ${entry.author}: ${entry.description}`);
+
+      if (entry.content.before) {
+        lines.push(`  - ${entry.content.before}`);
+      }
+      if (entry.content.after) {
+        lines.push(`  + ${entry.content.after}`);
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Export changelog to JSON (for programmatic consumption).
+   *
+   * @param entries - Array of changelog entries
+   * @returns JSON string
+   */
+  static toJSON(entries: ChangeEntry[]): string {
+    return JSON.stringify({
+      generated: new Date().toISOString(),
+      summary: this.getSummary(entries),
+      entries,
+    }, null, 2);
+  }
+
+  // ============================================================
+  // Unified API (Phase 2 Enhancement)
+  // ============================================================
+
+  /**
+   * Unified changelog generation - single entry point for all formats.
+   *
+   * Generates changelog from a document in the specified format.
+   * This is the recommended method for most use cases.
+   *
+   * @param doc - Document to extract revisions from
+   * @param options - Generation options including format
+   * @returns Formatted changelog string
+   *
+   * @example
+   * ```typescript
+   * // Generate Markdown changelog
+   * const md = ChangelogGenerator.generate(doc, { format: 'markdown' });
+   *
+   * // Generate HTML changelog
+   * const html = ChangelogGenerator.generate(doc, { format: 'html' });
+   *
+   * // Generate CSV with filtering
+   * const csv = ChangelogGenerator.generate(doc, {
+   *   format: 'csv',
+   *   filterAuthors: ['John Doe'],
+   *   sortBy: 'date',
+   *   sortOrder: 'desc'
+   * });
+   * ```
+   */
+  static generate(doc: Document, options?: ChangelogOptions): string {
+    const logger = getLogger();
+    const format = options?.format || 'markdown';
+
+    logger.info('Generating changelog', { format });
+
+    // Get entries with filtering
+    let entries = this.fromDocument(doc, options);
+
+    // Apply sorting if specified
+    if (options?.sortBy) {
+      entries = this.sortEntries(entries, options.sortBy, options.sortOrder || 'asc');
+    }
+
+    logger.info('Changelog entries processed', {
+      entries: entries.length,
+      format,
+      sorted: !!options?.sortBy
+    });
+
+    // Generate output in specified format
+    switch (format) {
+      case 'json':
+        return this.toJSON(entries);
+      case 'markdown':
+        return this.toMarkdown(entries, { includeMetadata: true });
+      case 'text':
+        return this.toPlainText(entries);
+      case 'html':
+        return this.toHTML(entries, options);
+      case 'csv':
+        return this.toCSV(entries);
+      default:
+        return this.toMarkdown(entries);
+    }
+  }
+
+  /**
+   * Export changelog to HTML format.
+   *
+   * Generates a complete HTML document with styling and structure.
+   *
+   * @param entries - Array of changelog entries
+   * @param options - HTML generation options
+   * @returns Complete HTML document string
+   *
+   * @example
+   * ```typescript
+   * const html = ChangelogGenerator.toHTML(entries);
+   * fs.writeFileSync('changelog.html', html);
+   * ```
+   */
+  static toHTML(entries: ChangeEntry[], options?: ChangelogOptions): string {
+    const summary = this.getSummary(entries);
+
+    // Group entries by category
+    const byCategory = new Map<ChangeCategory, ChangeEntry[]>();
+    for (const entry of entries) {
+      if (!byCategory.has(entry.category)) {
+        byCategory.set(entry.category, []);
+      }
+      byCategory.get(entry.category)!.push(entry);
+    }
+
+    const categoryTitles: Record<ChangeCategory, string> = {
+      content: 'Content Changes',
+      formatting: 'Formatting Changes',
+      structural: 'Structural Changes',
+      table: 'Table Changes',
+      hyperlink: 'Hyperlink Changes',
+      image: 'Image Changes',
+      field: 'Field Changes',
+      comment: 'Comment Changes',
+      bookmark: 'Bookmark Changes',
+      contentControl: 'Content Control Changes',
+    };
+
+    // Build HTML
+    let html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Document Changes</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      max-width: 900px;
+      margin: 0 auto;
+      padding: 20px;
+      line-height: 1.6;
+      color: #333;
+    }
+    h1 { color: #2c3e50; border-bottom: 2px solid #3498db; padding-bottom: 10px; }
+    h2 { color: #34495e; margin-top: 30px; }
+    .summary { background: #f8f9fa; padding: 15px; border-radius: 8px; margin-bottom: 20px; }
+    .summary p { margin: 5px 0; }
+    .category { margin-bottom: 30px; }
+    .change-list { list-style: none; padding: 0; }
+    .change-item {
+      background: #fff;
+      border: 1px solid #e9ecef;
+      border-radius: 6px;
+      padding: 12px 15px;
+      margin-bottom: 10px;
+    }
+    .change-item:hover { box-shadow: 0 2px 5px rgba(0,0,0,0.1); }
+    .change-description { font-weight: 500; color: #2c3e50; }
+    .change-meta { font-size: 0.85em; color: #7f8c8d; margin-top: 5px; }
+    .change-content { margin-top: 8px; font-size: 0.9em; }
+    .removed { color: #c0392b; text-decoration: line-through; }
+    .added { color: #27ae60; }
+    .badge {
+      display: inline-block;
+      padding: 2px 8px;
+      border-radius: 4px;
+      font-size: 0.75em;
+      font-weight: 600;
+      text-transform: uppercase;
+    }
+    .badge-insert { background: #d4edda; color: #155724; }
+    .badge-delete { background: #f8d7da; color: #721c24; }
+    .badge-formatting { background: #cce5ff; color: #004085; }
+    .badge-structural { background: #fff3cd; color: #856404; }
+    .badge-table { background: #e2e3e5; color: #383d41; }
+  </style>
+</head>
+<body>
+  <h1>Document Changes</h1>
+
+  <div class="summary">
+    <p><strong>Total Changes:</strong> ${summary.total}</p>`;
+
+    if (summary.dateRange) {
+      html += `
+    <p><strong>Date Range:</strong> ${summary.dateRange.earliest.toLocaleDateString()} - ${summary.dateRange.latest.toLocaleDateString()}</p>`;
+    }
+
+    const authors = Object.keys(summary.byAuthor);
+    if (authors.length > 0) {
+      html += `
+    <p><strong>Authors:</strong> ${authors.join(', ')}</p>`;
+    }
+
+    html += `
+  </div>
+`;
+
+    // Add sections by category
+    for (const [category, categoryEntries] of byCategory) {
+      if (categoryEntries.length === 0) continue;
+
+      html += `
+  <section class="category">
+    <h2>${categoryTitles[category]}</h2>
+    <ul class="change-list">`;
+
+      for (const entry of categoryEntries) {
+        const badgeClass = this.getBadgeClass(entry.revisionType);
+        const date = entry.date.toLocaleDateString();
+
+        html += `
+      <li class="change-item">
+        <span class="badge ${badgeClass}">${entry.revisionType}</span>
+        <div class="change-description">${this.escapeHTML(entry.description)}</div>
+        <div class="change-meta">${this.escapeHTML(entry.author)} - ${date}</div>`;
+
+        if (entry.content.before || entry.content.after) {
+          html += `
+        <div class="change-content">`;
+          if (entry.content.before) {
+            html += `<span class="removed">${this.escapeHTML(entry.content.before || '')}</span> `;
+          }
+          if (entry.content.after) {
+            html += `<span class="added">${this.escapeHTML(entry.content.after || '')}</span>`;
+          }
+          html += `</div>`;
+        }
+
+        html += `
+      </li>`;
+      }
+
+      html += `
+    </ul>
+  </section>`;
+    }
+
+    html += `
+</body>
+</html>`;
+
+    return html;
+  }
+
+  /**
+   * Export changelog to CSV format.
+   *
+   * Generates CSV data suitable for spreadsheet applications.
+   *
+   * @param entries - Array of changelog entries
+   * @param options - CSV generation options
+   * @returns CSV string
+   *
+   * @example
+   * ```typescript
+   * const csv = ChangelogGenerator.toCSV(entries);
+   * fs.writeFileSync('changelog.csv', csv);
+   * ```
+   */
+  static toCSV(entries: ChangeEntry[], options?: {
+    delimiter?: string;
+    includeHeaders?: boolean;
+  }): string {
+    const delimiter = options?.delimiter || ',';
+    const includeHeaders = options?.includeHeaders !== false;
+
+    const headers = [
+      'ID',
+      'Type',
+      'Category',
+      'Author',
+      'Date',
+      'Description',
+      'Before',
+      'After',
+      'Paragraph',
+      'Run'
+    ];
+
+    const lines: string[] = [];
+
+    if (includeHeaders) {
+      lines.push(headers.join(delimiter));
+    }
+
+    for (const entry of entries) {
+      const row = [
+        entry.id,
+        entry.revisionType,
+        entry.category,
+        this.escapeCSV(entry.author),
+        entry.date.toISOString(),
+        this.escapeCSV(entry.description),
+        this.escapeCSV(entry.content.before || ''),
+        this.escapeCSV(entry.content.after || ''),
+        entry.location.paragraphIndex?.toString() || '',
+        entry.location.runIndex?.toString() || '',
+      ];
+      lines.push(row.join(delimiter));
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Get timeline view - changes organized by date.
+   *
+   * Groups changelog entries by date (YYYY-MM-DD) for timeline visualization.
+   *
+   * @param entries - Array of changelog entries
+   * @returns Map of date strings to entries for that date
+   *
+   * @example
+   * ```typescript
+   * const timeline = ChangelogGenerator.getTimeline(entries);
+   * for (const [date, dayEntries] of timeline) {
+   *   console.log(`${date}: ${dayEntries.length} changes`);
+   * }
+   * ```
+   */
+  static getTimeline(entries: ChangeEntry[]): Map<string, ChangeEntry[]> {
+    const timeline = new Map<string, ChangeEntry[]>();
+
+    for (const entry of entries) {
+      const dateKey = entry.date.toISOString().split('T')[0]!; // YYYY-MM-DD
+      if (!timeline.has(dateKey)) {
+        timeline.set(dateKey, []);
+      }
+      timeline.get(dateKey)!.push(entry);
+    }
+
+    // Sort the map by date
+    const sortedTimeline = new Map<string, ChangeEntry[]>(
+      [...timeline.entries()].sort((a, b) => a[0].localeCompare(b[0]))
+    );
+
+    return sortedTimeline;
+  }
+
+  /**
+   * Get summary by element type.
+   *
+   * Groups entries by the type of document element they affect.
+   *
+   * @param entries - Array of changelog entries
+   * @returns Object with entries grouped by element type
+   */
+  static getSummaryByElement(entries: ChangeEntry[]): {
+    paragraphs: ChangeEntry[];
+    tables: ChangeEntry[];
+    sections: ChangeEntry[];
+    runs: ChangeEntry[];
+    hyperlinks: ChangeEntry[];
+  } {
+    return {
+      paragraphs: entries.filter(e =>
+        e.revisionType === 'paragraphPropertiesChange' ||
+        e.revisionType === 'numberingChange' ||
+        (e.revisionType === 'insert' && !e.location.runIndex) ||
+        (e.revisionType === 'delete' && !e.location.runIndex)
+      ),
+      tables: entries.filter(e =>
+        ['tablePropertiesChange', 'tableRowPropertiesChange',
+         'tableCellPropertiesChange', 'tableExceptionPropertiesChange',
+         'tableCellInsert', 'tableCellDelete', 'tableCellMerge'].includes(e.revisionType)
+      ),
+      sections: entries.filter(e =>
+        e.revisionType === 'sectionPropertiesChange'
+      ),
+      runs: entries.filter(e =>
+        e.revisionType === 'runPropertiesChange' ||
+        (e.revisionType === 'insert' && e.location.runIndex !== undefined) ||
+        (e.revisionType === 'delete' && e.location.runIndex !== undefined)
+      ),
+      hyperlinks: entries.filter(e =>
+        e.revisionType === 'hyperlinkChange'
+      ),
+    };
+  }
+
+  // ============================================================
+  // Helper Methods
+  // ============================================================
+
+  /**
+   * Sort entries by specified field.
+   * @internal
+   */
+  private static sortEntries(
+    entries: ChangeEntry[],
+    sortBy: 'date' | 'author' | 'type' | 'category',
+    order: 'asc' | 'desc'
+  ): ChangeEntry[] {
+    const sorted = [...entries].sort((a, b) => {
+      let comparison = 0;
+
+      switch (sortBy) {
+        case 'date':
+          comparison = a.date.getTime() - b.date.getTime();
+          break;
+        case 'author':
+          comparison = a.author.localeCompare(b.author);
+          break;
+        case 'type':
+          comparison = a.revisionType.localeCompare(b.revisionType);
+          break;
+        case 'category':
+          comparison = a.category.localeCompare(b.category);
+          break;
+      }
+
+      return order === 'desc' ? -comparison : comparison;
+    });
+
+    return sorted;
+  }
+
+  /**
+   * Get CSS badge class for revision type.
+   * @internal
+   */
+  private static getBadgeClass(type: RevisionType): string {
+    switch (type) {
+      case 'insert':
+      case 'moveTo':
+      case 'tableCellInsert':
+        return 'badge-insert';
+      case 'delete':
+      case 'moveFrom':
+      case 'tableCellDelete':
+        return 'badge-delete';
+      case 'runPropertiesChange':
+      case 'paragraphPropertiesChange':
+      case 'numberingChange':
+        return 'badge-formatting';
+      case 'sectionPropertiesChange':
+        return 'badge-structural';
+      case 'tablePropertiesChange':
+      case 'tableRowPropertiesChange':
+      case 'tableCellPropertiesChange':
+      case 'tableCellMerge':
+        return 'badge-table';
+      default:
+        return 'badge-formatting';
+    }
+  }
+
+  /**
+   * Escape HTML special characters.
+   * @internal
+   */
+  private static escapeHTML(str: string): string {
+    return str
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#039;');
+  }
+
+  /**
+   * Escape CSV special characters.
+   * @internal
+   */
+  private static escapeCSV(str: string): string {
+    // If string contains delimiter, newline, or quotes, wrap in quotes
+    if (str.includes(',') || str.includes('\n') || str.includes('"')) {
+      return `"${str.replace(/"/g, '""')}"`;
+    }
+    return str;
+  }
+}