documentation-hub 5.7.2

package/src/services/document/processors/HyperlinkProcessor.ts

@@ -0,0 +1,370 @@
+/**
+ * HyperlinkProcessor - Hyperlink manipulation and API integration
+ *
+ * Handles:
+ * - Hyperlink formatting standardization
+ * - PowerAutomate API integration for URL/text updates
+ * - Custom replacement rules
+ * - Internal hyperlink repair
+ * - URL update batch processing
+ */
+
+import {
+  Document,
+  Hyperlink,
+  Revision,
+} from "docxmlater";
+import type { DetailedHyperlinkInfo, HyperlinkType } from "@/types/hyperlink";
+import type { DocumentChange } from "@/types/session";
+import { logger } from "@/utils/logger";
+import { sanitizeHyperlinkText } from "@/utils/textSanitizer";
+import { extractLookupIds } from "@/utils/urlPatterns";
+import { hyperlinkService } from "../../HyperlinkService";
+import { DocXMLaterProcessor } from "../DocXMLaterProcessor";
+import { documentProcessingComparison } from "../DocumentProcessingComparison";
+
+const log = logger.namespace("HyperlinkProcessor");
+
+/**
+ * Result of URL update batch operation
+ */
+export interface UrlUpdateResult {
+  updated: number;
+  failed: Array<{
+    oldUrl: string;
+    newUrl: string;
+    error: unknown;
+    paragraphIndex?: number;
+  }>;
+}
+
+/**
+ * Result of hyperlink processing
+ */
+export interface HyperlinkProcessingResult {
+  updatedUrls: number;
+  updatedDisplayTexts: number;
+  standardizedCount: number;
+  changes: DocumentChange[];
+  processedLinks: Array<{
+    id: string;
+    url: string;
+    displayText: string;
+    type: HyperlinkType;
+    location: string;
+    status: "processed" | "skipped" | "error";
+    before: string;
+    after: string;
+    modifications: string[];
+  }>;
+  errorMessages: string[];
+}
+
+/**
+ * Options for hyperlink processing
+ */
+export interface HyperlinkProcessingOptions {
+  apiEndpoint?: string;
+  operations?: {
+    fixContentIds?: boolean;
+    updateTitles?: boolean;
+    processHyperlinks?: boolean;
+    standardizeHyperlinkColor?: boolean;
+    fixInternalHyperlinks?: boolean;
+  };
+  trackChanges?: boolean;
+  userProfile?: {
+    firstName: string;
+    lastName: string;
+    email: string;
+  };
+  customReplacements?: Array<{
+    find: string;
+    replace: string;
+    matchType: "contains" | "exact" | "startsWith";
+    applyTo: "url" | "text" | "both";
+  }>;
+}
+
+/**
+ * Hyperlink processing service
+ */
+export class HyperlinkProcessor {
+  private docXMLater: DocXMLaterProcessor;
+  private readonly DEBUG = process.env.NODE_ENV !== "production";
+
+  constructor() {
+    this.docXMLater = new DocXMLaterProcessor();
+  }
+
+  /**
+   * Standardize hyperlink formatting to Verdana 12pt blue underlined
+   */
+  async standardizeFormatting(doc: Document): Promise<number> {
+    let standardizedCount = 0;
+
+    try {
+      const hyperlinks = await this.docXMLater.extractHyperlinks(doc);
+      log.debug(`Found ${hyperlinks.length} hyperlinks to standardize`);
+
+      for (const { hyperlink, url, text } of hyperlinks) {
+        try {
+          hyperlink.setFormatting({
+            font: "Verdana",
+            size: 12,
+            color: "0000FF",
+            underline: "single",
+            bold: false,
+            italic: false,
+          });
+          standardizedCount++;
+          log.debug(`Standardized hyperlink: "${text}" (${url})`);
+        } catch (error) {
+          log.warn(`Failed to standardize hyperlink "${text}": ${error}`);
+        }
+      }
+
+      log.info(`Standardized ${standardizedCount} of ${hyperlinks.length} hyperlinks`);
+    } catch (error) {
+      log.error(`Error standardizing hyperlink formatting: ${error}`);
+      throw error;
+    }
+
+    return standardizedCount;
+  }
+
+  /**
+   * Apply URL updates to hyperlinks with track changes support
+   */
+  async applyUrlUpdates(
+    doc: Document,
+    urlMap: Map<string, string>,
+    author: string = "DocHub"
+  ): Promise<UrlUpdateResult> {
+    if (urlMap.size === 0) {
+      return { updated: 0, failed: [] };
+    }
+
+    const failedUrls: UrlUpdateResult["failed"] = [];
+    let updatedCount = 0;
+    const paragraphs = doc.getAllParagraphs();
+    const trackChangesEnabled = doc.isTrackChangesEnabled();
+
+    log.debug(`Processing ${paragraphs.length} paragraphs for URL updates`);
+
+    for (let paraIndex = 0; paraIndex < paragraphs.length; paraIndex++) {
+      const para = paragraphs[paraIndex];
+      const content = para.getContent();
+
+      for (const item of [...content]) {
+        if (item instanceof Hyperlink) {
+          const oldUrl = item.getUrl();
+
+          if (oldUrl && urlMap.has(oldUrl)) {
+            const newUrl = urlMap.get(oldUrl)!;
+
+            if (oldUrl === newUrl) {
+              continue;
+            }
+
+            try {
+              if (trackChangesEnabled) {
+                const oldHyperlink = item.clone();
+                item.setUrl(newUrl);
+
+                const deletion = Revision.createDeletion(author, [oldHyperlink]);
+                const insertion = Revision.createInsertion(author, [item]);
+
+                const replaced = para.replaceContent(item, [deletion, insertion]);
+
+                if (replaced) {
+                  const revisionManager = doc.getRevisionManager();
+                  revisionManager.register(deletion);
+                  revisionManager.register(insertion);
+                  log.debug(`Created tracked change for hyperlink URL: ${oldUrl} -> ${newUrl}`);
+                }
+              } else {
+                item.setUrl(newUrl);
+                log.debug(`Updated hyperlink URL: ${oldUrl} -> ${newUrl}`);
+              }
+
+              updatedCount++;
+            } catch (error) {
+              log.error(`Failed to update URL at paragraph ${paraIndex}: ${oldUrl} -> ${newUrl}`, error);
+              failedUrls.push({
+                oldUrl,
+                newUrl,
+                error,
+                paragraphIndex: paraIndex,
+              });
+            }
+          }
+        }
+      }
+    }
+
+    if (failedUrls.length > 0) {
+      log.warn(`URL update completed with ${failedUrls.length} failures`);
+    } else {
+      log.info(`Successfully updated ${updatedCount} hyperlink URLs`);
+    }
+
+    return { updated: updatedCount, failed: failedUrls };
+  }
+
+  /**
+   * Process custom URL and text replacements
+   */
+  async processCustomReplacements(
+    doc: Document,
+    replacements: NonNullable<HyperlinkProcessingOptions["customReplacements"]>
+  ): Promise<{ updatedUrls: number; updatedTexts: number }> {
+    const hyperlinks = await this.docXMLater.extractHyperlinks(doc);
+    let updatedUrls = 0;
+    let updatedTexts = 0;
+
+    for (const { hyperlink, url, text } of hyperlinks) {
+      for (const rule of replacements) {
+        if (rule.applyTo === "url" || rule.applyTo === "both") {
+          if (url && this.matchesPattern(url, rule.find, rule.matchType)) {
+            const newUrl = url.replace(rule.find, rule.replace);
+            hyperlink.setUrl(newUrl);
+            updatedUrls++;
+          }
+        }
+
+        if (rule.applyTo === "text" || rule.applyTo === "both") {
+          if (this.matchesPattern(text, rule.find, rule.matchType)) {
+            const newText = text.replace(rule.find, rule.replace);
+            hyperlink.setText(newText);
+            updatedTexts++;
+          }
+        }
+      }
+    }
+
+    return { updatedUrls, updatedTexts };
+  }
+
+  /**
+   * Fix internal hyperlinks - repair broken bookmarks
+   */
+  async fixInternalHyperlinks(doc: Document): Promise<number> {
+    const hyperlinks = await this.docXMLater.extractHyperlinks(doc);
+    let fixedCount = 0;
+
+    for (const { hyperlink, text } of hyperlinks) {
+      const anchor = hyperlink.getAnchor();
+      if (!anchor) continue;
+
+      const bookmarkExists = doc.hasBookmark(anchor);
+
+      if (!bookmarkExists) {
+        if (text) {
+          const matchingHeading = this.findHeadingByText(doc, text);
+          if (matchingHeading) {
+            const newBookmark = this.createBookmarkForHeading(doc, matchingHeading, anchor);
+            if (newBookmark) {
+              fixedCount++;
+              log.info(`Created bookmark "${anchor}" for heading "${text}"`);
+            }
+          }
+        }
+      }
+    }
+
+    return fixedCount;
+  }
+
+  /**
+   * Find matching API result for a URL
+   */
+  findMatchingApiResult(url: string, apiResultsMap: Map<string, unknown>): unknown {
+    if (!url || !apiResultsMap || apiResultsMap.size === 0) {
+      return null;
+    }
+
+    const lookupIds = extractLookupIds(url);
+    if (!lookupIds) {
+      return null;
+    }
+
+    if (lookupIds.contentId) {
+      const result = apiResultsMap.get(lookupIds.contentId);
+      if (result) {
+        log.debug(`Matched by Content_ID: ${lookupIds.contentId}`);
+        return result;
+      }
+    }
+
+    if (lookupIds.documentId) {
+      const result = apiResultsMap.get(lookupIds.documentId);
+      if (result) {
+        log.debug(`Matched by Document_ID: ${lookupIds.documentId}`);
+        return result;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Pattern matching helper
+   */
+  private matchesPattern(
+    text: string,
+    pattern: string,
+    matchType: "contains" | "exact" | "startsWith"
+  ): boolean {
+    switch (matchType) {
+      case "exact":
+        return text === pattern;
+      case "startsWith":
+        return text.startsWith(pattern);
+      case "contains":
+      default:
+        return text.includes(pattern);
+    }
+  }
+
+  /**
+   * Find heading by text content
+   */
+  private findHeadingByText(doc: Document, searchText: string): unknown | null {
+    const normalizedSearch = searchText.trim().toLowerCase();
+    const paragraphs = doc.getAllParagraphs();
+
+    for (const para of paragraphs) {
+      const style = para.getStyle();
+
+      if (style && (style.startsWith("Heading") || style.includes("Heading"))) {
+        const paraText = (para.getText() || "").trim().toLowerCase();
+        if (paraText === normalizedSearch) {
+          return para;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Create bookmark for heading
+   */
+  private createBookmarkForHeading(
+    doc: Document,
+    heading: unknown,
+    bookmarkName: string
+  ): boolean {
+    try {
+      // Implementation depends on docxmlater API
+      // This is a placeholder for the actual implementation
+      return false;
+    } catch (error) {
+      log.warn(`Failed to create bookmark: ${error}`);
+      return false;
+    }
+  }
+}
+
+export const hyperlinkProcessor = new HyperlinkProcessor();

package/src/services/document/processors/ListProcessor.ts

@@ -0,0 +1,257 @@
+/**
+ * ListProcessor - List formatting and bullet/numbering operations
+ *
+ * Handles:
+ * - List bullet settings and uniformity
+ * - Numbered list formatting
+ * - List prefix standardization (font, size, color)
+ * - Indentation configuration
+ * - Spacing between list items
+ */
+
+import { Document, inchesToTwips } from "docxmlater";
+import { logger } from "@/utils/logger";
+
+const log = logger.namespace("ListProcessor");
+
+/**
+ * Configuration for list indentation levels
+ */
+export interface ListIndentationLevel {
+  level: number;
+  symbolIndent: number; // Symbol/bullet position in inches
+  textIndent: number; // Text position in inches
+  bulletChar?: string;
+  numberedFormat?: string;
+}
+
+/**
+ * List bullet settings
+ */
+export interface ListBulletSettings {
+  enabled: boolean;
+  indentationLevels: ListIndentationLevel[];
+  spacingBetweenItems: number;
+}
+
+/**
+ * Result of list processing
+ */
+export interface ListProcessingResult {
+  listsUpdated: number;
+  levelsProcessed: number;
+}
+
+/**
+ * List processing service
+ */
+export class ListProcessor {
+  private readonly DEBUG = process.env.NODE_ENV !== "production";
+
+  /**
+   * Apply list indentation settings to all lists in the document
+   */
+  async applyListIndentation(
+    doc: Document,
+    settings: ListBulletSettings
+  ): Promise<ListProcessingResult> {
+    if (!settings.enabled || !settings.indentationLevels.length) {
+      return { listsUpdated: 0, levelsProcessed: 0 };
+    }
+
+    let listsUpdated = 0;
+    let levelsProcessed = 0;
+    const paragraphs = doc.getAllParagraphs();
+
+    for (const para of paragraphs) {
+      const numbering = para.getNumbering();
+      if (!numbering) continue;
+
+      const level = numbering.level || 0;
+      const indentSetting = settings.indentationLevels.find((l) => l.level === level);
+
+      if (indentSetting) {
+        // Validate indentation - symbolIndent must be less than textIndent
+        if (indentSetting.symbolIndent >= indentSetting.textIndent) {
+          log.warn(
+            `Invalid indentation for level ${level}: symbolIndent (${indentSetting.symbolIndent}) ` +
+            `must be less than textIndent (${indentSetting.textIndent}). Skipping.`
+          );
+          continue;
+        }
+
+        try {
+          // Apply indentation using individual methods
+          para.setLeftIndent(inchesToTwips(indentSetting.textIndent));
+          // Hanging indent is implemented as a negative first-line indent
+          const hangingTwips = inchesToTwips(indentSetting.textIndent - indentSetting.symbolIndent);
+          para.setFirstLineIndent(-hangingTwips);
+
+          // Apply spacing if configured
+          if (settings.spacingBetweenItems > 0) {
+            para.setSpaceAfter(settings.spacingBetweenItems * 20); // Convert to twips
+          }
+
+          listsUpdated++;
+          levelsProcessed++;
+        } catch (error) {
+          log.warn(`Failed to apply indentation to list item: ${error}`);
+        }
+      }
+    }
+
+    log.info(`Applied indentation to ${listsUpdated} list items`);
+    return { listsUpdated, levelsProcessed };
+  }
+
+  /**
+   * Standardize list prefix formatting (bullet/number font, size, color)
+   * Uses NumberingLevel API setters instead of raw XML manipulation.
+   */
+  async standardizeListPrefixFormatting(doc: Document): Promise<number> {
+    let standardizedCount = 0;
+
+    try {
+      const numberingManager = doc.getNumberingManager();
+      if (!numberingManager) {
+        log.warn("No numbering manager available for list prefix standardization");
+        return 0;
+      }
+
+      const abstractNums = numberingManager.getAllAbstractNumberings();
+      log.debug(`Found ${abstractNums.length} abstract numberings to process`);
+
+      // Special bullet fonts that should be preserved (used for special characters like open/closed circles)
+      const specialBulletFonts = ["Webdings", "Wingdings", "Symbol", "Wingdings 2", "Wingdings 3", "Courier New"];
+
+      for (const abstractNum of abstractNums) {
+        for (let levelIndex = 0; levelIndex <= 8; levelIndex++) {
+          const level = abstractNum.getLevel(levelIndex);
+          if (!level) continue;
+
+          // Check if this level uses a special bullet font that should be preserved
+          const currentFont = level.getProperties().font;
+          const preserveFont = currentFont && specialBulletFonts.includes(currentFont);
+
+          // Preserve special bullet fonts, otherwise use Verdana
+          const fontToUse = preserveFont ? currentFont : "Verdana";
+          level.setFont(fontToUse);
+          level.setColor("000000");
+          level.setFontSize(24); // 24 half-points = 12pt
+          level.setBold(false);
+
+          standardizedCount++;
+
+          if (preserveFont) {
+            log.debug(`Standardized list level ${levelIndex}: preserved ${currentFont} font, 12pt black`);
+          } else {
+            log.debug(`Standardized list level ${levelIndex}: Verdana 12pt black`);
+          }
+        }
+      }
+
+      if (standardizedCount > 0) {
+        log.info(`Standardized ${standardizedCount} list prefix levels`);
+      }
+    } catch (error) {
+      log.error(`Error standardizing list prefix formatting: ${error}`);
+      throw error;
+    }
+
+    return standardizedCount;
+  }
+
+  /**
+   * Apply bullet uniformity - standardize bullet characters
+   * Uses NumberingLevel API setters instead of raw XML manipulation.
+   */
+  async applyBulletUniformity(
+    doc: Document,
+    settings: ListBulletSettings
+  ): Promise<ListProcessingResult> {
+    let listsUpdated = 0;
+
+    try {
+      const numberingManager = doc.getNumberingManager();
+      if (!numberingManager) {
+        return { listsUpdated: 0, levelsProcessed: 0 };
+      }
+
+      const abstractNums = numberingManager.getAllAbstractNumberings();
+
+      // Update bullet characters based on settings
+      for (const levelConfig of settings.indentationLevels) {
+        if (!levelConfig.bulletChar) continue;
+
+        for (const abstractNum of abstractNums) {
+          const level = abstractNum.getLevel(levelConfig.level);
+          if (!level) continue;
+
+          // Only update bullet lists, not numbered lists
+          if (level.getFormat() !== "bullet") continue;
+
+          level.setText(levelConfig.bulletChar);
+          listsUpdated++;
+        }
+      }
+
+      if (listsUpdated > 0) {
+        log.info(`Updated bullet characters in ${listsUpdated} list levels`);
+      }
+    } catch (error) {
+      log.error(`Error applying bullet uniformity: ${error}`);
+    }
+
+    return { listsUpdated, levelsProcessed: listsUpdated };
+  }
+
+  /**
+   * Check if a paragraph is a bullet list item
+   */
+  isBulletList(doc: Document, numId: number): boolean {
+    try {
+      const numberingManager = doc.getNumberingManager();
+      const instance = numberingManager?.getNumberingInstance(numId);
+      if (!instance) return false;
+
+      const abstractNumId = instance.getAbstractNumId();
+      const abstractNum = numberingManager?.getAbstractNumbering(abstractNumId);
+      if (!abstractNum) return false;
+
+      const level0 = abstractNum.getLevel(0);
+      return level0?.getFormat() === "bullet";
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Check if a paragraph is a numbered list item
+   */
+  isNumberedList(doc: Document, numId: number): boolean {
+    try {
+      const numberingManager = doc.getNumberingManager();
+      const instance = numberingManager?.getNumberingInstance(numId);
+      if (!instance) return false;
+
+      const abstractNumId = instance.getAbstractNumId();
+      const abstractNum = numberingManager?.getAbstractNumbering(abstractNumId);
+      if (!abstractNum) return false;
+
+      const level0 = abstractNum.getLevel(0);
+      const format = level0?.getFormat();
+      return (
+        format === "decimal" ||
+        format === "lowerLetter" ||
+        format === "upperLetter" ||
+        format === "lowerRoman" ||
+        format === "upperRoman"
+      );
+    } catch {
+      return false;
+    }
+  }
+
+}
+
+export const listProcessor = new ListProcessor();