docxmlater 10.3.5 → 10.4.0

package/src/formatting/StylesManager.ts

@@ -192,6 +192,42 @@ export class StylesManager {
     return this.styles.get(styleId);
   }
 
+  /**
+   * Clones an existing style with a new ID and optional name
+   *
+   * Deep-copies the source style (including all run, paragraph, and table
+   * formatting) and registers the clone with the new ID. If `newName` is
+   * not provided, the clone's name is set to the new ID.
+   *
+   * @param sourceId - ID of the style to clone
+   * @param newId - ID for the cloned style (must be unique)
+   * @param newName - Display name for the clone (defaults to newId)
+   * @returns The cloned Style, or undefined if source not found
+   *
+   * @example
+   * ```typescript
+   * // Create a variant of Heading1
+   * const variant = stylesManager.cloneStyle('Heading1', 'Heading1Blue', 'Blue Heading 1');
+   * variant?.setRunFormatting({ ...variant.getRunFormatting(), color: '0000FF' });
+   *
+   * // Clone a custom style for a different section
+   * stylesManager.cloneStyle('CustomNote', 'CustomNoteAlt');
+   * ```
+   */
+  cloneStyle(sourceId: string, newId: string, newName?: string): Style | undefined {
+    const source = this.getStyle(sourceId);
+    if (!source) return undefined;
+
+    const props = source.getProperties();
+    props.styleId = newId;
+    props.name = newName ?? newId;
+    props.isDefault = false; // Clones should never be default
+
+    const cloned = new Style(props);
+    this.addStyle(cloned);
+    return cloned;
+  }
+
   /**
    * Checks if a style exists or can be loaded
    * @param styleId - Style ID to check

package/src/helpers/CleanupHelper.ts

@@ -437,7 +437,7 @@ export class CleanupHelper {
     };
 
     // Helper to process paragraph content
-    const processParagraph = (paragraph: any): void => {
+    const processParagraph = (paragraph: Paragraph): void => {
       for (const item of paragraph.getContent()) {
         // Process all Hyperlink instances (both internal AND external)
         if (item instanceof Hyperlink) {

package/src/images/ImageOptimizer.ts

@@ -69,9 +69,6 @@ function buildPngChunk(type: string, data: Buffer): Buffer {
 // PNG Re-compression
 // =============================================================================
 
-/** Chunks that must be preserved for correct PNG rendering */
-const ESSENTIAL_CHUNK_TYPES = new Set(['IHDR', 'PLTE', 'tRNS', 'IDAT', 'IEND']);
-
 /**
  * Re-compresses a PNG buffer at zlib level 9 and strips non-essential metadata chunks.
  * Returns the optimized buffer, or null if the PNG is invalid/cannot be optimized.

package/src/index.ts

@@ -35,7 +35,7 @@ export {
   isShape,
   isTextBox,
 } from './elements/Paragraph';
-export { Run, RunFormatting, ThemeColorValue } from './elements/Run';
+export { Run, RunFormatting, ThemeColorValue, LanguageConfig } from './elements/Run';
 export {
   Section,
   PageOrientation,

package/src/managers/DrawingManager.ts

@@ -256,14 +256,16 @@ export class DrawingManager {
    * @param drawing Drawing to check
    * @returns True if PreservedDrawing
    */
-  private isPreservedDrawing(drawing: any): drawing is PreservedDrawing {
+  private isPreservedDrawing(drawing: unknown): drawing is PreservedDrawing {
     return (
-      drawing &&
+      !!drawing &&
       typeof drawing === 'object' &&
       'type' in drawing &&
       'xml' in drawing &&
       'relationshipIds' in drawing &&
-      (drawing.type === 'smartart' || drawing.type === 'chart' || drawing.type === 'wordart')
+      ((drawing as PreservedDrawing).type === 'smartart' ||
+        (drawing as PreservedDrawing).type === 'chart' ||
+        (drawing as PreservedDrawing).type === 'wordart')
     );
   }
 

package/src/tracking/CLAUDE.md

@@ -0,0 +1,30 @@
+# Tracking Module
+
+`src/tracking/` — Change tracking context for revision-aware document editing.
+
+## Interfaces & Classes
+
+### TrackingContext (interface)
+
+Contract for tracking changes on document elements. Methods:
+
+- `trackRunPropertyChange(run, previousProps)` — creates `w:rPrChange`
+- `trackParagraphPropertyChange(para, previousProps)` — creates `w:pPrChange`
+- `trackTableChange(table, previousProps)` — creates `w:tblPrChange`
+- `trackInsertion(element)` / `trackDeletion(element)` — wraps in `w:ins`/`w:del`
+- `flushPendingChanges()` — converts queued changes to Revision objects
+- `isEnabled()` — check if tracking is active
+
+### DocumentTrackingContext (`DocumentTrackingContext.ts`)
+
+Implementation of `TrackingContext`. Key behaviors:
+
+- **State:** enabled flag, author name, `trackFormatting` toggle, pending changes map
+- **Consolidation:** Groups changes by element with time-window keys to batch similar edits (prevents one revision per keystroke)
+- **PrChange application:** Creates/merges `*PrChange` markers (`rPrChange`, `pPrChange`, `tblPrChange`, `tcPrChange`, `sectPrChange`) per ECMA-376
+- **Full snapshot tracking:** Stores complete previous properties (not deltas) for table/cell/section changes
+- **WeakMap for element IDs:** Prevents GC issues with stable element references
+
+## Key Pattern
+
+Call `doc.flushPendingChanges()` before inspecting `pPrChange` or `rPrChange` in tests — pending changes are batched and only materialized on flush or save.

package/src/types/CLAUDE.md

@@ -0,0 +1,39 @@
+# Types Module
+
+`src/types/` — TypeScript type definitions shared across modules.
+
+## Files
+
+### `formatting.ts`
+Formatting-related types used by Document search/replace and paragraph formatting:
+- `BorderStyleType`, `BorderStyle`, `ParagraphBorder` — border definitions
+- `ShadingPattern`, `ParagraphShading` — re-exported from CommonTypes
+- `TabAlignment`, `TabLeader`, `TabStop` — tab stop configuration
+- `FindOptions`, `ReplaceOptions`, `SearchResult` — text search/replace options
+- `EmphasisType`, `ListPrefix`, `FormatOptions`, `StyleApplyOptions` — style application
+
+### `styleConfig.ts`
+Style configuration interfaces for Document's style application methods:
+- `StyleRunFormatting` — character-level formatting (font, size, bold, etc.)
+- `StyleParagraphFormatting` — paragraph-level formatting (alignment, spacing, indentation)
+- `StyleConfig`, `Heading2Config`, `NormalConfig` — predefined style configurations
+- `ApplyStylesOptions` — options for `doc.applyStyles()` / `doc.applyStylesFromObjects()`
+- `ApplyCustomFormattingOptions` — deprecated alias for `ApplyStylesOptions`
+
+### `settings-types.ts`
+Document settings interfaces:
+- `DocumentProtection` — password protection settings
+- `RevisionViewSettings` — revision display mode
+- `TrackChangesSettings` — track changes configuration
+- `WebSettingsInfo` — web settings (div cleanup, encoding)
+
+### `list-types.ts`
+List detection and normalization:
+- `ListCategory`, `NumberFormat`, `BulletFormat` — list type classification
+- `ListDetectionResult`, `ListAnalysis` — detection output
+- `ListNormalizationOptions`, `ListNormalizationReport` — normalization config/results
+
+### `compatibility-types.ts`
+Word compatibility mode types:
+- `CompatSetting` — individual compatibility setting (name, uri, val)
+- `CompatibilityInfo` — full compatibility state (mode value, legacy flags, modern settings)

package/src/types/formatting.ts

@@ -56,12 +56,12 @@ export type { ShadingConfig as ParagraphShading } from '../elements/CommonTypes'
 /**
  * Tab stop alignment
  */
-export type TabAlignment = 'left' | 'center' | 'right' | 'decimal' | 'bar' | 'clear';
+export type TabAlignment = 'left' | 'center' | 'right' | 'decimal' | 'bar' | 'clear' | 'num';
 
 /**
  * Tab leader character
  */
-export type TabLeader = 'none' | 'dot' | 'dash' | 'underscore' | 'heavy' | 'middleDot';
+export type TabLeader = 'none' | 'dot' | 'hyphen' | 'underscore' | 'heavy' | 'middleDot';
 
 /**
  * Tab stop configuration

package/src/utils/CLAUDE.md

@@ -2,6 +2,21 @@
 
 `src/utils/` — Standalone utilities (22 TypeScript files) for unit conversions, revision processing, validation, logging, and helpers.
 
+## Architecture Classification
+
+**Pure utilities** (no element/core imports — safe to use anywhere):
+- `units.ts`, `validation.ts`, `deepClone.ts`, `dateFormatting.ts`, `errorHandling.ts`
+- `xmlSanitization.ts`, `formatting.ts`, `parsingHelpers.ts`, `logger.ts`, `diagnostics.ts`
+- `textDiff.ts`, `list-detection.ts`, `corruptionDetection.ts`
+
+**Domain-specific processors** (import from elements/core — should arguably be in `src/processors/`):
+- `acceptRevisions.ts`, `RevisionWalker.ts`, `InMemoryRevisionAcceptor.ts`
+- `SelectiveRevisionAcceptor.ts`, `RevisionAwareProcessor.ts`, `MoveOperationHelper.ts`
+- `ChangelogGenerator.ts`, `ShadingResolver.ts`, `stripTrackedChanges.ts`
+- `CompatibilityUpgrader.ts`, `cnfStyleDecoder.ts`
+
+This split explains the 36+ dependency-cruiser warnings about utils importing elements — the domain-specific files are processors, not pure utilities.
+
 ## Unit Conversions (`units.ts`)
 
 40+ conversion functions between twips, EMUs, points, half-points, pixels, inches, centimeters.

package/src/utils/ChangelogGenerator.ts

@@ -198,7 +198,7 @@ export class ChangelogGenerator {
   static fromRevisions(
     revisions: Revision[],
     options?: ChangelogOptions,
-    doc?: Document
+    _doc?: Document
   ): ChangeEntry[] {
     const logger = getLogger();
     const opts = {
@@ -619,7 +619,6 @@ export class ChangelogGenerator {
    */
   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 =
@@ -676,7 +675,7 @@ export class ChangelogGenerator {
   /**
    * Generate description for a hyperlink change revision.
    */
-  private static describeHyperlinkChange(revision: Revision, maxLength: number): string {
+  private static describeHyperlinkChange(revision: Revision, _maxLength: number): string {
     const prevProps = revision.getPreviousProperties() || {};
     const newProps = revision.getNewProperties() || {};
     const changes: string[] = [];
@@ -883,7 +882,7 @@ export class ChangelogGenerator {
         // Truncate if too long
         return json.length > 100 ? json.substring(0, 97) + '...' : json;
       } catch (e) {
-        getLogger().debug('Failed to stringify value', { error: String(e) });
+        getLogger().warn('Failed to stringify value for changelog', { error: String(e) });
         return '[complex value]';
       }
     }
@@ -1203,7 +1202,7 @@ export class ChangelogGenerator {
    * fs.writeFileSync('changelog.html', html);
    * ```
    */
-  static toHTML(entries: ChangeEntry[], options?: ChangelogOptions): string {
+  static toHTML(entries: ChangeEntry[], _options?: ChangelogOptions): string {
     const summary = this.getSummary(entries);
 
     // Group entries by category

package/src/utils/InMemoryRevisionAcceptor.ts

@@ -18,13 +18,9 @@ import type { Document } from '../core/Document';
 import { Paragraph } from '../elements/Paragraph';
 import type { ParagraphContent } from '../elements/Paragraph';
 import { Revision, RevisionType } from '../elements/Revision';
-import type { Run } from '../elements/Run';
-import type { Hyperlink } from '../elements/Hyperlink';
 import { isRunContent, isHyperlinkContent, isImageRunContent } from '../elements/RevisionContent';
-import type { ImageRun } from '../elements/ImageRun';
 import { ComplexField } from '../elements/Field';
 import { Table } from '../elements/Table';
-import { Section } from '../elements/Section';
 import { getGlobalLogger, createScopedLogger, ILogger } from './logger';
 
 /**
@@ -68,11 +64,6 @@ export interface AcceptRevisionsResult {
   emptyTablesRemoved: number;
 }
 
-/**
- * Revision types that represent content changes (contain actual text/runs)
- */
-const CONTENT_REVISION_TYPES: RevisionType[] = ['insert', 'delete', 'moveFrom', 'moveTo'];
-
 /**
  * Revision types that represent property/formatting changes
  */

package/src/utils/RevisionAwareProcessor.ts

@@ -13,7 +13,6 @@
 
 import type { Document } from '../core/Document';
 import { Revision, RevisionType } from '../elements/Revision';
-import { RevisionManager } from '../elements/RevisionManager';
 import { ChangeCategory, ChangeLocation } from './ChangelogGenerator';
 
 /**
@@ -382,7 +381,7 @@ export class RevisionAwareProcessor {
    * @param runIndex - Optional run index
    * @returns Conflicting revision or null
    */
-  static checkConflict(doc: Document, paragraphIndex: number, runIndex?: number): Revision | null {
+  static checkConflict(doc: Document, paragraphIndex: number, _runIndex?: number): Revision | null {
     const revisionManager = doc.getRevisionManager();
     if (!revisionManager) {
       return null;
@@ -407,7 +406,7 @@ export class RevisionAwareProcessor {
   static getAffectedRevisions(
     doc: Document,
     paragraphIndex: number,
-    runIndex?: number
+    _runIndex?: number
   ): Revision[] {
     const revisionManager = doc.getRevisionManager();
     if (!revisionManager) {

package/src/utils/SelectiveRevisionAcceptor.ts

@@ -16,7 +16,6 @@ import type { Document } from '../core/Document';
 import type { Paragraph, ParagraphContent } from '../elements/Paragraph';
 import { Revision, RevisionType } from '../elements/Revision';
 import type { Run } from '../elements/Run';
-import type { Hyperlink } from '../elements/Hyperlink';
 import { isRunContent, isHyperlinkContent } from '../elements/RevisionContent';
 import { ChangeCategory } from './ChangelogGenerator';
 import { SelectionCriteria } from './RevisionAwareProcessor';
@@ -533,27 +532,6 @@ export class SelectiveRevisionAcceptor {
     return this.accept(doc, { categories: ['content'] });
   }
 
-  /**
-   * Partition revisions into matching and non-matching based on criteria.
-   */
-  private static partitionRevisions(
-    revisions: Revision[],
-    criteria: SelectionCriteria
-  ): { matching: Revision[]; nonMatching: Revision[] } {
-    const matching: Revision[] = [];
-    const nonMatching: Revision[] = [];
-
-    for (const rev of revisions) {
-      if (this.matchesCriteria(rev, criteria)) {
-        matching.push(rev);
-      } else {
-        nonMatching.push(rev);
-      }
-    }
-
-    return { matching, nonMatching };
-  }
-
   /**
    * Check if a revision matches the given criteria.
    */
@@ -642,21 +620,4 @@ export class SelectiveRevisionAcceptor {
 
     return 'content';
   }
-
-  /**
-   * Create an empty result.
-   */
-  private static emptyResult(): SelectiveAcceptResult {
-    return {
-      accepted: [],
-      rejected: [],
-      remaining: [],
-      summary: {
-        totalProcessed: 0,
-        acceptedCount: 0,
-        rejectedCount: 0,
-        remainingCount: 0,
-      },
-    };
-  }
 }

package/src/utils/ShadingResolver.ts

@@ -18,7 +18,6 @@ import type { Table } from '../elements/Table';
 import type { TableCell } from '../elements/TableCell';
 import type { StylesManager } from '../formatting/StylesManager';
 import { getActiveConditionalsInPriorityOrder } from './cnfStyleDecoder';
-import type { ConditionalFormattingType } from '../formatting/Style';
 
 /**
  * Resolves the effective shading for a table cell through the style hierarchy.

package/src/utils/acceptRevisions.ts

@@ -281,7 +281,7 @@ class RevisionAcceptor {
 
     result = result.replace(insRegex, (insMatch) => {
       // For each image reference inside this insertion, generate a unique new ID
-      return insMatch.replace(/r:embed="(rId\d+)"/g, (embedMatch, oldId) => {
+      return insMatch.replace(/r:embed="(rId\d+)"/g, (_embedMatch, oldId) => {
         // Generate new unique ID for THIS occurrence
         const newId = this.getNextRelationshipId(existingIds);
         existingIds.add(newId);

package/src/utils/stripTrackedChanges.ts

@@ -107,7 +107,7 @@ class TrackedChangesStripper {
 
     result = result.replace(insRegex, (insMatch) => {
       // For each image reference inside this insertion, generate a unique new ID
-      return insMatch.replace(/r:embed="(rId\d+)"/g, (embedMatch, oldId) => {
+      return insMatch.replace(/r:embed="(rId\d+)"/g, (_embedMatch, oldId) => {
         // Generate new unique ID for THIS occurrence
         const newId = this.getNextRelationshipId(existingIds);
         existingIds.add(newId);

package/src/utils/units.ts

@@ -185,7 +185,8 @@ export function pointsToCm(points: number): number {
  * @returns Value in half-points
  */
 export function pointsToHalfPoints(points: number): number {
-  return points * UNITS.HALF_POINTS_PER_POINT;
+  // Round to nearest integer — w:sz/w:szCs require ST_HpsMeasure (unsigned integer)
+  return Math.round(points * UNITS.HALF_POINTS_PER_POINT);
 }
 
 /**

package/src/validation/CLAUDE.md

@@ -0,0 +1,40 @@
+# Validation Module
+
+`src/validation/` — Revision validation, rule definitions, and auto-fix.
+
+## Classes
+
+### RevisionValidator (`RevisionValidator.ts`)
+
+Static validation class. Entry point: `validate(doc, options?)`.
+
+Runs all rules with configurable strictness (`strict` / `normal` / `lenient`). Returns `ValidationResult` with categorized issues (errors, warnings, infos) and summary stats.
+
+Individual validators: `validateRevisionIds()`, `validateMovePairs()`, `validateAuthors()`, `validateDates()`, `validateContent()`, `validateSequentialIds()`.
+
+### ValidationRules (`ValidationRules.ts`)
+
+10 rules organized by severity:
+
+| Rule   | Severity | Description                | Auto-fixable |
+|--------|----------|----------------------------|-------------|
+| REV001 | Error    | Duplicate revision IDs     | Yes         |
+| REV002 | Error    | Missing authors            | Yes         |
+| REV003 | Error    | Orphaned moveFrom          | Yes         |
+| REV004 | Error    | Orphaned moveTo            | Yes         |
+| REV101 | Warning  | Missing dates              | Yes         |
+| REV102 | Warning  | Invalid date format        | Yes         |
+| REV103 | Warning  | Empty revisions            | Yes         |
+| REV104 | Warning  | Non-sequential IDs         | Yes         |
+| REV201 | Info     | Large revision count       | No          |
+| REV202 | Info     | Old revision dates         | No          |
+
+**Auto-fix dependency order:** REV001 -> REV002 -> REV003/004 -> REV103 -> REV104
+
+### RevisionAutoFixer (`RevisionAutoFixer.ts`)
+
+Applies fixes in correct dependency order. Supports dry-run mode via `preview()`.
+
+Entry point: `fix(doc, options?)`. Returns `AutoFixResult` with detailed actions taken.
+
+Individual fixers: `fixDuplicateIds()`, `fixMissingAuthors()`, `fixOrphanedMoveMarkers()`, `fixEmptyRevisions()`, `fixNonSequentialIds()`.

package/src/validation/RevisionAutoFixer.ts

@@ -9,6 +9,7 @@
 
 import type { Document } from '../core/Document';
 import type { Revision } from '../elements/Revision';
+import type { RevisionManager } from '../elements/RevisionManager';
 import {
   REVISION_RULES,
   AutoFixOptions,
@@ -387,7 +388,7 @@ export class RevisionAutoFixer {
    * @returns Array of fix actions
    */
   static fixEmptyRevisions(
-    revisionManager: any,
+    revisionManager: RevisionManager,
     revisions: Revision[],
     dryRun?: boolean
   ): FixAction[] {