docxmlater 10.0.1 → 10.0.3

package/src/utils/diagnostics.ts

@@ -0,0 +1,129 @@
+/**
+ * Diagnostic logging utilities for debugging document processing
+ * @module diagnostics
+ */
+
+export interface DiagnosticConfig {
+  enabled: boolean;
+  logParsing: boolean;
+  logSerialization: boolean;
+  logTextDirection: boolean;
+  verbose: boolean;
+}
+
+const defaultConfig: DiagnosticConfig = {
+  enabled: false,
+  logParsing: false,
+  logSerialization: false,
+  logTextDirection: false,
+  verbose: false,
+};
+
+let config: DiagnosticConfig = { ...defaultConfig };
+
+/**
+ * Enable diagnostic logging
+ */
+export function enableDiagnostics(options: Partial<DiagnosticConfig> = {}): void {
+  config = {
+    ...defaultConfig,
+    enabled: true,
+    ...options,
+  };
+}
+
+/**
+ * Disable diagnostic logging
+ */
+export function disableDiagnostics(): void {
+  config = { ...defaultConfig };
+}
+
+/**
+ * Get current diagnostic configuration
+ */
+export function getDiagnosticConfig(): DiagnosticConfig {
+  return { ...config };
+}
+
+/**
+ * Log parsing activity
+ */
+export function logParsing(message: string, data?: unknown): void {
+  if (config.enabled && config.logParsing) {
+    console.log(`[PARSE] ${message}`, data !== undefined ? data : '');
+  }
+}
+
+/**
+ * Log serialization activity
+ */
+export function logSerialization(message: string, data?: unknown): void {
+  if (config.enabled && config.logSerialization) {
+    console.log(`[SERIALIZE] ${message}`, data !== undefined ? data : '');
+  }
+}
+
+/**
+ * Log text direction properties
+ */
+export function logTextDirection(message: string, data?: unknown): void {
+  if (config.enabled && config.logTextDirection) {
+    console.log(`[TEXT-DIR] ${message}`, data !== undefined ? data : '');
+  }
+}
+
+/**
+ * Log verbose details
+ */
+export function logVerbose(message: string, data?: unknown): void {
+  if (config.enabled && config.verbose) {
+    console.log(`[VERBOSE] ${message}`, data !== undefined ? data : '');
+  }
+}
+
+/**
+ * Log paragraph content summary
+ */
+export function logParagraphContent(
+  source: 'parsing' | 'serialization',
+  paraIndex: number,
+  runs: { text: string; rtl?: boolean }[],
+  bidi?: boolean
+): void {
+  if (!config.enabled) return;
+
+  const logger = source === 'parsing' ? logParsing : logSerialization;
+
+  logger(`Paragraph ${paraIndex}:`);
+  logger(`  BiDi: ${bidi !== undefined ? bidi : 'not set'}`);
+  logger(`  Runs (${runs.length}):`);
+
+  runs.forEach((run, idx) => {
+    const rtlStatus = run.rtl ? ' [RTL]' : '';
+    logger(`    ${idx + 1}. "${run.text}"${rtlStatus}`);
+  });
+
+  const fullText = runs.map(r => r.text).join('');
+  logger(`  Combined text: "${fullText}"`);
+}
+
+/**
+ * Compare text before and after processing
+ */
+export function logTextComparison(
+  label: string,
+  before: string,
+  after: string
+): void {
+  if (!config.enabled) return;
+
+  if (before !== after) {
+    console.log(`[TEXT-CHANGE] ${label}:`);
+    console.log(`  Before: "${before}"`);
+    console.log(`  After:  "${after}"`);
+    console.log(`  MISMATCH DETECTED!`);
+  } else if (config.verbose) {
+    logVerbose(`${label}: Text preserved correctly`);
+  }
+}

package/src/utils/errorHandling.ts

@@ -0,0 +1,80 @@
+/**
+ * Error handling utilities for consistent error processing
+ * Ensures all caught errors are properly typed and handled
+ */
+
+/**
+ * Type guard to check if a value is an Error object
+ * @param error - The value to check
+ * @returns True if the value is an Error instance
+ */
+export function isError(error: unknown): error is Error {
+  return error instanceof Error;
+}
+
+/**
+ * Converts unknown error to Error object
+ * Ensures we always have a proper Error with message property
+ * @param error - The error to normalize (can be anything)
+ * @returns Normalized Error object
+ */
+export function toError(error: unknown): Error {
+  if (isError(error)) {
+    return error;
+  }
+
+  // Handle string errors
+  if (typeof error === 'string') {
+    return new Error(error);
+  }
+
+  // Handle objects with message property
+  if (error && typeof error === 'object' && 'message' in error) {
+    return new Error(String(error.message));
+  }
+
+  // Fallback for any other type
+  return new Error(String(error));
+}
+
+/**
+ * Wraps an error with additional context
+ * Useful for adding file paths, operation names, etc.
+ * @param error - The original error
+ * @param context - Additional context to prepend to error message
+ * @returns New Error with combined message and original stack
+ */
+export function wrapError(error: unknown, context: string): Error {
+  const originalError = toError(error);
+  const wrappedError = new Error(`${context}: ${originalError.message}`);
+
+  // Preserve original stack trace if available
+  if (originalError.stack) {
+    wrappedError.stack = `${wrappedError.message}\nCaused by: ${originalError.stack}`;
+  }
+
+  return wrappedError;
+}
+
+/**
+ * Safe error message extraction
+ * Returns error message or generic fallback
+ * @param error - The error to extract message from
+ * @param fallback - Fallback message if extraction fails
+ * @returns Error message string
+ */
+export function getErrorMessage(error: unknown, fallback = 'Unknown error occurred'): string {
+  if (isError(error)) {
+    return error.message;
+  }
+
+  if (typeof error === 'string') {
+    return error;
+  }
+
+  if (error && typeof error === 'object' && 'message' in error) {
+    return String(error.message);
+  }
+
+  return fallback;
+}

package/src/utils/formatting.ts

@@ -0,0 +1,213 @@
+/**
+ * Formatting utilities for deep merging and cloning formatting objects
+ * Used for style inheritance and applying formatting
+ */
+
+/**
+ * Deep merges two formatting objects, with override taking precedence
+ * Used for style inheritance and applying formatting
+ *
+ * @param base - Base formatting object
+ * @param override - Override formatting object (takes precedence)
+ * @returns Merged formatting object
+ *
+ * @example
+ * ```typescript
+ * const baseFormat = { bold: true, fontSize: 24 };
+ * const overrideFormat = { fontSize: 28, italic: true };
+ * const result = mergeFormatting(baseFormat, overrideFormat);
+ * // Result: { bold: true, fontSize: 28, italic: true }
+ * ```
+ */
+export function mergeFormatting<T extends Record<string, any>>(
+  base: T,
+  override: Partial<T>
+): T {
+  const result = { ...base };
+
+  for (const [key, value] of Object.entries(override)) {
+    if (value === undefined) continue;
+
+    if (typeof value === 'object' && !Array.isArray(value) && value !== null) {
+      // Deep merge nested objects
+      result[key as keyof T] = mergeFormatting(
+        result[key as keyof T] || ({} as any),
+        value
+      );
+    } else {
+      // Direct assignment for primitives
+      result[key as keyof T] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Deep clones a formatting object
+ * Creates a completely independent copy with no shared references
+ *
+ * @param formatting - Formatting object to clone
+ * @returns Cloned formatting object
+ *
+ * @example
+ * ```typescript
+ * const original = { bold: true, indentation: { left: 100 } };
+ * const cloned = cloneFormatting(original);
+ * cloned.indentation.left = 200; // Doesn't affect original
+ * ```
+ */
+export function cloneFormatting<T>(formatting: T): T {
+  return JSON.parse(JSON.stringify(formatting));
+}
+
+/**
+ * Checks if a formatting object has any defined properties
+ *
+ * @param formatting - Formatting object to check
+ * @returns True if the object has at least one defined property
+ *
+ * @example
+ * ```typescript
+ * hasFormatting({}) // false
+ * hasFormatting({ bold: true }) // true
+ * hasFormatting({ bold: undefined }) // false
+ * ```
+ */
+export function hasFormatting(formatting: Record<string, unknown>): boolean {
+  for (const value of Object.values(formatting)) {
+    if (value !== undefined && value !== null) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Removes undefined and null properties from a formatting object
+ * Useful for cleaning up formatting before comparison or serialization
+ *
+ * @param formatting - Formatting object to clean
+ * @returns Cleaned formatting object with no undefined/null values
+ *
+ * @example
+ * ```typescript
+ * const dirty = { bold: true, italic: undefined, fontSize: null, underline: false };
+ * const clean = cleanFormatting(dirty);
+ * // Result: { bold: true, underline: false }
+ * ```
+ */
+export function cleanFormatting<T extends Record<string, any>>(formatting: T): Partial<T> {
+  const cleaned: Partial<T> = {};
+
+  for (const [key, value] of Object.entries(formatting)) {
+    if (value !== undefined && value !== null) {
+      if (typeof value === 'object' && !Array.isArray(value)) {
+        // Recursively clean nested objects
+        const cleanedNested = cleanFormatting(value);
+        if (Object.keys(cleanedNested).length > 0) {
+          cleaned[key as keyof T] = cleanedNested as any;
+        }
+      } else {
+        cleaned[key as keyof T] = value;
+      }
+    }
+  }
+
+  return cleaned;
+}
+
+/**
+ * Compares two formatting objects for equality
+ * Performs deep comparison of all properties
+ *
+ * @param format1 - First formatting object
+ * @param format2 - Second formatting object
+ * @returns True if the formatting objects are equal
+ *
+ * @example
+ * ```typescript
+ * const a = { bold: true, fontSize: 24 };
+ * const b = { bold: true, fontSize: 24 };
+ * const c = { bold: true, fontSize: 28 };
+ * isEqualFormatting(a, b) // true
+ * isEqualFormatting(a, c) // false
+ * ```
+ */
+export function isEqualFormatting(
+  format1: Record<string, unknown>,
+  format2: Record<string, unknown>
+): boolean {
+  // Quick reference check
+  if (format1 === format2) return true;
+
+  // Null/undefined checks
+  if (!format1 || !format2) return false;
+
+  // Get all keys from both objects
+  const keys1 = Object.keys(format1);
+  const keys2 = Object.keys(format2);
+
+  // Check if they have the same number of properties
+  if (keys1.length !== keys2.length) return false;
+
+  // Check all properties
+  for (const key of keys1) {
+    const val1 = format1[key];
+    const val2 = format2[key];
+
+    // Both undefined/null - considered equal
+    if ((val1 === undefined || val1 === null) && (val2 === undefined || val2 === null)) {
+      continue;
+    }
+
+    // One is undefined/null and the other isn't
+    if ((val1 === undefined || val1 === null) !== (val2 === undefined || val2 === null)) {
+      return false;
+    }
+
+    // Check nested objects
+    if (typeof val1 === 'object' && val1 !== null && typeof val2 === 'object' && val2 !== null && !Array.isArray(val1) && !Array.isArray(val2)) {
+      if (!isEqualFormatting(val1 as Record<string, unknown>, val2 as Record<string, unknown>)) return false;
+    } else if (val1 !== val2) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Applies default values to a formatting object for any undefined properties
+ *
+ * @param formatting - Formatting object to apply defaults to
+ * @param defaults - Default values
+ * @returns Formatting object with defaults applied
+ *
+ * @example
+ * ```typescript
+ * const format = { bold: true };
+ * const defaults = { bold: false, italic: false, fontSize: 24 };
+ * const result = applyDefaults(format, defaults);
+ * // Result: { bold: true, italic: false, fontSize: 24 }
+ * ```
+ */
+export function applyDefaults<T extends Record<string, any>>(
+  formatting: Partial<T>,
+  defaults: T
+): T {
+  const result = { ...defaults };
+
+  for (const [key, value] of Object.entries(formatting)) {
+    if (value !== undefined) {
+      if (typeof value === 'object' && !Array.isArray(value) && value !== null && typeof defaults[key] === 'object') {
+        // Deep merge nested objects
+        result[key as keyof T] = applyDefaults(value, defaults[key]);
+      } else {
+        result[key as keyof T] = value;
+      }
+    }
+  }
+
+  return result;
+}

package/src/utils/list-detection.ts

@@ -0,0 +1,274 @@
+/**
+ * List Detection Utilities for docxmlater
+ *
+ * Provides functions to detect typed list prefixes and analyze
+ * paragraph list properties.
+ */
+
+import type { Paragraph } from "../elements/Paragraph";
+import type {
+  ListCategory,
+  ListDetectionResult,
+  NumberFormat,
+  BulletFormat,
+} from "../types/list-types";
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+/**
+ * Regex patterns for typed list prefixes.
+ * Order matters: more specific patterns first.
+ */
+export const TYPED_LIST_PATTERNS: Record<string, RegExp> = {
+  // Numbered patterns (capture the marker for validation)
+  decimal: /^(\d+)[.)]\s+/,
+  lowerLetter: /^([a-z])[.)]\s+/,
+  upperLetter: /^([A-Z])[.)]\s+/,
+  lowerRoman: /^((?:i{1,3}|iv|vi{0,3}|ix|x{1,3}))[.)]\s+/i,
+
+  // Bullet patterns
+  bullet: /^[•●○◦▪■□]\s+/,
+  dash: /^[-–—]\s+/,
+  arrow: /^[►▸▶→]\s+/,
+};
+
+/** Map pattern names to categories */
+export const PATTERN_TO_CATEGORY: Record<string, ListCategory> = {
+  decimal: "numbered",
+  lowerLetter: "numbered",
+  upperLetter: "numbered",
+  lowerRoman: "numbered",
+  bullet: "bullet",
+  dash: "bullet",
+  arrow: "bullet",
+};
+
+/**
+ * Map typed prefix format to Word numbering level.
+ * Word's default multilevel list uses:
+ *   Level 0: 1., 2., 3. (decimal)
+ *   Level 1: a., b., c. (lowerLetter)
+ *   Level 2: i., ii., iii. (lowerRoman)
+ */
+export const FORMAT_TO_LEVEL: Record<string, number> = {
+  decimal: 0,      // 1., 2., 3.
+  lowerLetter: 1,  // a., b., c.
+  upperLetter: 1,  // A., B., C.
+  lowerRoman: 2,   // i., ii., iii.
+  upperRoman: 2,   // I., II., III.
+  bullet: 0,       // Top-level bullet (filled circle)
+  dash: 0,         // Top-level dash marker
+  arrow: 0,        // Top-level arrow marker
+};
+
+/**
+ * Get the Word numbering level for a given format.
+ * Returns 0 (top level) for decimal or unknown formats.
+ */
+export function getLevelFromFormat(format: string | null): number {
+  if (!format) return 0;
+  return FORMAT_TO_LEVEL[format] ?? 0;
+}
+
+/**
+ * Word standard indentation values in twips.
+ * Level 0: 720 twips (0.5 inch) left indent
+ * Level 1: 1080 twips (0.75 inch) left indent
+ * Level 2: 1440 twips (1 inch) left indent
+ * Each subsequent level adds 360 twips.
+ */
+const WORD_BASE_INDENT = 720;
+const INDENT_PER_LEVEL = 360;
+
+// =============================================================================
+// CORE DETECTION FUNCTIONS
+// =============================================================================
+
+/**
+ * Infer list level from indentation.
+ * Uses standard Word indentation: 720 twips for level 0, +360 per level.
+ */
+export function inferLevelFromIndentation(indentTwips: number): number {
+  if (indentTwips < WORD_BASE_INDENT) return 0;
+  return Math.floor((indentTwips - WORD_BASE_INDENT) / INDENT_PER_LEVEL);
+}
+
+/**
+ * Infer list level from relative indentation (baseline already subtracted).
+ * Used when normalizing lists within a table cell where the baseline
+ * indentation varies per cell.
+ */
+export function inferLevelFromRelativeIndentation(relativeIndentTwips: number): number {
+  if (relativeIndentTwips <= 0) return 0;
+  return Math.min(8, Math.floor(relativeIndentTwips / INDENT_PER_LEVEL));
+}
+
+/**
+ * Detect typed list prefix in text.
+ * Returns the matched prefix and format type.
+ *
+ * Special handling for abbreviations:
+ * - Single letter prefixes (A., B., P.) are NOT treated as list markers
+ *   if the remaining text also starts with a letter+period pattern,
+ *   indicating an abbreviation like "P.O. Box", "U.S. Army", etc.
+ */
+export function detectTypedPrefix(text: string): {
+  prefix: string | null;
+  format: NumberFormat | BulletFormat | null;
+  category: ListCategory;
+} {
+  for (const [format, regex] of Object.entries(TYPED_LIST_PATTERNS)) {
+    const match = text.match(regex);
+    if (match) {
+      // Special check for single-letter patterns (lowerLetter, upperLetter)
+      // to avoid false positives on abbreviations like "P.O. Box", "U.S.", "A.M."
+      if (format === "lowerLetter" || format === "upperLetter") {
+        const remaining = text.substring(match[0].length);
+        // If remaining text starts with another letter followed by period,
+        // this is likely an abbreviation, not a list marker
+        if (/^[A-Za-z]\./.test(remaining)) {
+          continue; // Skip this pattern, try others
+        }
+      }
+
+      return {
+        prefix: match[0],
+        format: format as NumberFormat | BulletFormat,
+        category: PATTERN_TO_CATEGORY[format] ?? "none",
+      };
+    }
+  }
+
+  return { prefix: null, format: null, category: "none" };
+}
+
+/**
+ * Get the left indentation from a paragraph in twips.
+ */
+export function getParagraphIndentation(paragraph: Paragraph): number {
+  const formatting = paragraph.getFormatting();
+  return formatting?.indentation?.left ?? 0;
+}
+
+/**
+ * Main detection function: analyze a single paragraph for list properties.
+ */
+export function detectListType(paragraph: Paragraph): ListDetectionResult {
+  const text = paragraph.getText();
+  const indentation = getParagraphIndentation(paragraph);
+  const numbering = paragraph.getNumbering();
+
+  // Priority 1: Real Word list with <w:numPr>
+  if (numbering?.numId !== undefined && numbering.numId !== 0) {
+    return {
+      category: "numbered", // Default, caller can refine with NumberingManager lookup
+      isWordList: true,
+      typedPrefix: null,
+      inferredLevel: numbering.level ?? 0,
+      format: null, // Would need numbering.xml lookup
+      numId: numbering.numId,
+      ilvl: numbering.level ?? 0,
+      indentationTwips: indentation,
+    };
+  }
+
+  // Priority 2: Typed prefix detection
+  const typed = detectTypedPrefix(text);
+  if (typed.prefix) {
+    return {
+      category: typed.category,
+      isWordList: false,
+      typedPrefix: typed.prefix,
+      // Use FORMAT to determine level, not indentation!
+      // decimal=0, lowerLetter=1, lowerRoman=2
+      inferredLevel: getLevelFromFormat(typed.format),
+      format: typed.format,
+      numId: null,
+      ilvl: null,
+      indentationTwips: indentation,
+    };
+  }
+
+  // Priority 3: Not a list
+  return {
+    category: "none",
+    isWordList: false,
+    typedPrefix: null,
+    inferredLevel: 0,
+    format: null,
+    numId: null,
+    ilvl: null,
+    indentationTwips: indentation,
+  };
+}
+
+/**
+ * Validate that a typed prefix sequence is reasonable.
+ * E.g., "1. 2. 3." is valid, "1. 5. 2." is suspicious.
+ */
+export function validateListSequence(
+  paragraphs: { detection: ListDetectionResult; text: string }[]
+): { valid: boolean; warnings: string[] } {
+  const warnings: string[] = [];
+  let lastDecimal = 0;
+  let lastLetter = "";
+
+  for (const { detection } of paragraphs) {
+    if (!detection.typedPrefix || detection.category !== "numbered") continue;
+
+    const match = /^(\d+|[a-zA-Z]+)/.exec(detection.typedPrefix);
+    if (!match?.[1]) continue;
+
+    const marker = match[1];
+
+    // Check decimal sequence
+    if (/^\d+$/.test(marker)) {
+      const num = parseInt(marker, 10);
+      if (lastDecimal > 0 && num !== lastDecimal + 1 && num !== 1) {
+        warnings.push(`Unexpected number sequence: ${lastDecimal} → ${num}`);
+      }
+      lastDecimal = num;
+    }
+
+    // Check letter sequence
+    if (/^[a-z]$/i.test(marker)) {
+      const letter = marker.toLowerCase();
+      if (
+        lastLetter &&
+        letter.charCodeAt(0) !== lastLetter.charCodeAt(0) + 1 &&
+        letter !== "a"
+      ) {
+        warnings.push(`Unexpected letter sequence: ${lastLetter} → ${letter}`);
+      }
+      lastLetter = letter;
+    }
+  }
+
+  return { valid: warnings.length === 0, warnings };
+}
+
+/**
+ * Determine the list category for a given numId by checking the abstractNum.
+ * This requires access to the NumberingManager.
+ */
+export function getListCategoryFromFormat(
+  format: string | undefined
+): ListCategory {
+  if (!format) return "none";
+
+  if (["bullet", "dash", "arrow"].includes(format)) {
+    return "bullet";
+  }
+
+  if (
+    ["decimal", "lowerLetter", "upperLetter", "lowerRoman", "upperRoman"].includes(
+      format
+    )
+  ) {
+    return "numbered";
+  }
+
+  return "none";
+}