uniword 1.2.5 → 1.3.0

data/lib/uniword/builder/comment_anchorer.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Builder
+    # Anchors a comment to a body paragraph.
+    #
+    # Word anchors a comment with three pieces of markup around the
+    # commented content:
+    #
+    #   <w:commentRangeStart w:id="0"/>
+    #   ... commented runs ...
+    #   <w:commentRangeEnd w:id="0"/>
+    #   <w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr>
+    #       <w:commentReference w:id="0"/></w:r>
+    #
+    # Paragraph uses mixed-content serialization, so the anchor elements
+    # must also be recorded in the paragraph's element_order — fresh
+    # paragraphs get a complete order built from their current content,
+    # parsed paragraphs get the new entries inserted in place (a second
+    # anchor on the same paragraph nests inside the first, matching
+    # Word's canonical output).
+    #
+    # @example Anchor a comment on the last paragraph of a document
+    #   CommentAnchorer.anchor(document.body.paragraphs.last, "1")
+    class CommentAnchorer
+      # Character style Word applies to comment reference runs.
+      REFERENCE_STYLE = "CommentReference"
+
+      # Paragraph content element names in mapping declaration order,
+      # excluding pPr and the comment anchor elements (handled
+      # separately). Mirrors Paragraph's `xml do` block; used to rebuild
+      # element_order for programmatically anchored paragraphs.
+      CONTENT_ELEMENTS = %w[
+        hyperlink bookmarkStart bookmarkEnd fldChar instrText
+        commentReference AlternateContent sdt oMathPara oMath proofErr
+        fldSimple
+      ].freeze
+
+      # Element name → collection reader, used to size element_order
+      # entries without dynamic dispatch.
+      COLLECTION_READERS = {
+        "hyperlink" => :hyperlinks.to_proc,
+        "bookmarkStart" => :bookmark_starts.to_proc,
+        "bookmarkEnd" => :bookmark_ends.to_proc,
+        "fldChar" => :field_chars.to_proc,
+        "instrText" => :instr_text.to_proc,
+        "commentReference" => :comment_references.to_proc,
+        "AlternateContent" => :alternate_content.to_proc,
+        "sdt" => :sdts.to_proc,
+        "oMathPara" => :o_math_paras.to_proc,
+        "oMath" => :o_maths.to_proc,
+        "proofErr" => :proof_errors.to_proc,
+        "fldSimple" => :simple_fields.to_proc,
+      }.freeze
+
+      class << self
+        # Anchor a comment around the paragraph's current content.
+        # No-op when the paragraph is nil (comment stays unanchored but
+        # remains valid in word/comments.xml).
+        #
+        # @param paragraph [Wordprocessingml::Paragraph, nil] anchor target
+        # @param comment_id [String, Integer] ID of the comment entry
+        # @return [void]
+        def anchor(paragraph, comment_id)
+          return unless paragraph
+
+          id = comment_id.to_s
+          paragraph.comment_range_starts << range_start(id)
+          paragraph.comment_range_ends << range_end(id)
+          paragraph.runs << reference_run(id)
+          sync_element_order(paragraph)
+        end
+
+        private
+
+        def range_start(id)
+          Wordprocessingml::CommentRangeStart.new(id: id)
+        end
+
+        def range_end(id)
+          Wordprocessingml::CommentRangeEnd.new(id: id)
+        end
+
+        # The run carrying w:commentReference, styled with Word's
+        # CommentReference character style.
+        def reference_run(id)
+          run = Wordprocessingml::Run.new
+          run.properties = Wordprocessingml::RunProperties.new
+          run.properties.style =
+            Properties::RunStyleReference.new(value: REFERENCE_STYLE)
+          run.comment_reference = Wordprocessingml::CommentReference.new(id: id)
+          run
+        end
+
+        # Record the anchor elements in element_order so mixed-content
+        # serialization emits them in anchor position. Parsed paragraphs
+        # with a consistent order get in-place insertion; anything else
+        # gets a full rebuild from current content.
+        def sync_element_order(paragraph)
+          order = paragraph.element_order
+          paragraph.element_order =
+            if order.nil? || order.empty? || inconsistent?(order, paragraph)
+              fresh_element_order(paragraph)
+            else
+              inserted_element_order(order, paragraph)
+            end
+        end
+
+        # element_order tracks every collection except the just-added
+        # anchor elements; any mismatch means it is stale and a rebuild
+        # is safer than insertion.
+        def inconsistent?(order, paragraph)
+          count(order, "r") != paragraph.runs.size - 1 ||
+            count(order, "commentRangeStart") !=
+              paragraph.comment_range_starts.size - 1 ||
+            count(order, "commentRangeEnd") !=
+              paragraph.comment_range_ends.size - 1
+        end
+
+        def count(order, name)
+          order.count { |e| e.name == name }
+        end
+
+        # Insert the new anchor entries into an existing order: the start
+        # marker after the last existing start marker (or pPr), the end
+        # marker before the first reference run, and the new reference
+        # run's entry last.
+        def inserted_element_order(order, paragraph)
+          entries = order.dup
+          insert_start_entry(entries)
+          insert_end_entry(entries, paragraph)
+          entries << xml_element("r")
+          entries
+        end
+
+        def insert_start_entry(entries)
+          pos = entries.rindex { |e| e.name == "commentRangeStart" }
+          pos ||= entries.index { |e| e.name == "pPr" }
+          entries.insert(pos ? pos + 1 : 0, xml_element("commentRangeStart"))
+        end
+
+        def insert_end_entry(entries, paragraph)
+          ref_index = paragraph.runs.index(&:comment_reference)
+          r_positions = entries.each_index.select do |i|
+            entries[i].name == "r"
+          end
+          if ref_index && r_positions[ref_index]
+            entries.insert(r_positions[ref_index],
+                           xml_element("commentRangeEnd"))
+          else
+            entries << xml_element("commentRangeEnd")
+          end
+        end
+
+        # Build a complete element_order from the paragraph's current
+        # content: pPr, start markers, content runs and other content,
+        # end markers, then the reference runs — Word's canonical
+        # anchor layout.
+        def fresh_element_order(paragraph)
+          prefix_entries(paragraph) + content_entries(paragraph) +
+            suffix_entries(paragraph)
+        end
+
+        # pPr plus all commentRangeStart entries.
+        def prefix_entries(paragraph)
+          entries = []
+          entries << xml_element("pPr") if paragraph.properties
+          paragraph.comment_range_starts.size.times do
+            entries << xml_element("commentRangeStart")
+          end
+          entries
+        end
+
+        # All commentRangeEnd entries plus the reference runs' entries.
+        def suffix_entries(paragraph)
+          entries = []
+          paragraph.comment_range_ends.size.times do
+            entries << xml_element("commentRangeEnd")
+          end
+          reference_runs(paragraph).size.times { entries << xml_element("r") }
+          entries
+        end
+
+        # Entries for all non-anchor content in mapping declaration
+        # order, excluding reference runs (appended after end markers).
+        def content_entries(paragraph)
+          entries = []
+          content_run_count(paragraph).times { entries << xml_element("r") }
+          CONTENT_ELEMENTS.each do |name|
+            count = element_count(paragraph, name)
+            count.times { entries << xml_element(name) }
+          end
+          entries
+        end
+
+        def content_run_count(paragraph)
+          paragraph.runs.size - reference_runs(paragraph).size
+        end
+
+        def reference_runs(paragraph)
+          paragraph.runs.select(&:comment_reference)
+        end
+
+        # Collection size for a named content element, derived from the
+        # paragraph's mapped collections (single elements count as 1).
+        def element_count(paragraph, name)
+          reader = COLLECTION_READERS[name]
+          collection = reader&.call(paragraph)
+          return 0 if collection.nil?
+          return collection.size if collection.is_a?(Array)
+
+          1
+        end
+
+        def xml_element(name)
+          Lutaml::Xml::Element.new("Element", name)
+        end
+      end
+    end
+  end
+end

data/lib/uniword/builder/document_builder.rb

@@ -35,10 +35,18 @@ module Uniword
         Wordprocessingml::DocumentRoot
       end
 
+      # Every DocumentBuilder carries an IdAllocator — the single ID
+      # authority — so build-time allocations (images, hyperlinks,
+      # paragraph ids) and the save path draw from one registry.
+      # Reuses an explicit allocator or one already on the model;
+      # otherwise populates one seeded from the model's current
+      # relationships (loaded documents keep their rIds; fresh models
+      # start empty).
       def initialize(model = nil, allocator: nil)
         super(model)
-        @allocator = allocator
-        @model.allocator = allocator if allocator
+        @allocator = allocator || @model.allocator ||
+          Docx::IdAllocator.populate_from_package(@model)
+        @model.allocator = @allocator
         @footnote_builder = FootnoteBuilder.new(self, allocator: @allocator)
       end
 
@@ -216,6 +224,10 @@ module Uniword
         sec.type = type
         block.call(sec) if block_given?
         @model.body.section_properties ||= sec.build
+        # Register section-level headers/footers so their sectPr
+        # references resolve to real parts at save time.
+        sec.header_models.each { |t, hf| (@model.headers ||= {})[t] = hf }
+        sec.footer_models.each { |t, hf| (@model.footers ||= {})[t] = hf }
         sec
       end
 
@@ -472,14 +484,35 @@ module Uniword
         self
       end
 
-      # Create a comment and store it in the document's comments collection.
+      # Create a comment, register it in the document's comments
+      # collection (serialized to word/comments.xml on save), and anchor
+      # it around the most recently added body paragraph with
+      # commentRangeStart/commentRangeEnd markers and a CommentReference
+      # run. With no preceding paragraph the comment stays unanchored.
       #
       # @param author [String] Comment author name
       # @param text [String, nil] Comment text
       # @param initials [String, nil] Author initials
       # @yield [CommentBuilder] Builder for rich comment content
       # @return [Comment] The created Comment model
-      def comment(author:, text: nil, initials: nil, &block)
+      # Create a comment and store it in the document's comments
+      # collection.
+      #
+      # Without `on:`, the comment is anchored around the yielded
+      # paragraph (or the document's last paragraph when no block is
+      # given). With `on:`, the comment is anchored around an existing
+      # paragraph — anywhere in the document, including table cells.
+      #
+      # @param author [String] Comment author name
+      # @param text [String, nil] Comment text
+      # @param initials [String, nil] Author initials
+      # @param on [Wordprocessingml::Paragraph, Integer, nil] Anchor
+      #   target: a paragraph object, or an index into body paragraphs
+      # @yield [CommentBuilder] Builder for rich comment content
+      # @return [Comment] The created Comment model
+      # @raise [ArgumentError] when `on` is neither a Paragraph nor an
+      #   index of an existing body paragraph
+      def comment(author:, text: nil, initials: nil, on: nil, &block)
         comment_id = @allocator ? @allocator.alloc_comment_id : begin
           @comment_counter ||= 0
           @comment_counter += 1
@@ -493,8 +526,10 @@ module Uniword
         cb << text if text
         block.call(cb) if block_given?
         comment_obj = cb.build
-        @model.comments ||= []
-        @model.comments << comment_obj
+        comments_part.add_comment(comment_obj)
+        CommentAnchorer.anchor(comment_anchor_target(on),
+                               comment_obj.comment_id)
+        ensure_comment_reference_style
         comment_obj
       end
 
@@ -597,6 +632,62 @@ module Uniword
       def save(path)
         @model.to_file(path)
       end
+
+      private
+
+      # The document's comments collection, migrating legacy Array
+      # storage (assigned by earlier builder versions) into a
+      # CommentsPart so comments serialize to word/comments.xml.
+      #
+      # @return [Uniword::CommentsPart] The comments collection
+      def comments_part
+        case (existing = @model.comments)
+        when Uniword::CommentsPart then existing
+        when Array
+          part = Uniword::CommentsPart.new
+          existing.each { |c| part.add_comment(c) }
+          @model.comments = part
+        else
+          @model.comments = Uniword::CommentsPart.new
+        end
+      end
+
+      # Resolve the paragraph a comment anchors to: the explicit `on`
+      # target when given, else the document's last body paragraph.
+      def comment_anchor_target(on)
+        case on
+        when nil then @model.body&.paragraphs&.last
+        when Wordprocessingml::Paragraph then on
+        when Integer
+          @model.body&.paragraphs&.[](on) ||
+            raise(ArgumentError, "no body paragraph at index #{on}")
+        else
+          raise ArgumentError,
+                "comment target must be a Paragraph or paragraph index, " \
+                "got #{on.class}"
+        end
+      end
+
+      # Register Word's built-in CommentReference character style when
+      # absent, so the anchor run's rStyle resolves against styles.xml
+      # (the reconciler strips dangling style references).
+      #
+      # @return [void]
+      def ensure_comment_reference_style
+        styles = @model.styles_configuration
+        return if styles.style_by_id(CommentAnchorer::REFERENCE_STYLE)
+
+        styles.add_style(
+          Wordprocessingml::Style.new(
+            type: "character",
+            styleId: CommentAnchorer::REFERENCE_STYLE,
+            name: Wordprocessingml::StyleName.new(val: "annotation reference"),
+            uiPriority: Wordprocessingml::UiPriority.new(val: 99),
+            semiHidden: Wordprocessingml::SemiHidden.new,
+            unhideWhenUsed: Wordprocessingml::UnhideWhenUsed.new,
+          )
+        )
+      end
     end
   end
 end

data/lib/uniword/builder/image_builder.rb

@@ -27,7 +27,7 @@ module Uniword
       # Picture namespace URI for GraphicData
       PIC_URI = "http://schemas.openxmlformats.org/drawingml/2006/picture"
 
-      IMAGE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image"
+      IMAGE_REL_TYPE = Ooxml::PartRegistry.find_by_key(:image).rel_type
 
       # Register an image part on the document for DOCX packaging.
       #
@@ -36,14 +36,15 @@ module Uniword
       # @return [String] Relationship ID (e.g., 'rId5')
       def self.register_image(document, path)
         root = document.is_a?(Uniword::Builder::DocumentBuilder) ? document.model : document
-        alloc = document.is_a?(Uniword::Builder::DocumentBuilder) ? document.allocator : nil
+        alloc = if document.is_a?(Uniword::Builder::DocumentBuilder)
+                  document.allocator
+                elsif root
+                  root.allocator ||= Docx::IdAllocator.new
+                end
 
         target = "media/#{File.basename(path)}"
         r_id = if alloc
                  alloc.alloc_rid(target: target, type: IMAGE_REL_TYPE)
-               elsif root
-                 root.image_parts ||= {}
-                 "rId#{root.image_parts.size + 1}"
                else
                  "rId#{deterministic_id('img_rid', path)}"
                end

data/lib/uniword/builder/run_utils.rb

@@ -22,6 +22,7 @@ module Uniword
         return false if run.alternate_content
         return false if run.footnote_reference
         return false if run.endnote_reference
+        return false if run.comment_reference
         return false if run.field_char
         return false if run.instr_text
         return false if run.position_tab
@@ -45,6 +46,7 @@ module Uniword
         return false if run.alternate_content
         return false if run.footnote_reference
         return false if run.endnote_reference
+        return false if run.comment_reference
         return false if run.field_char
         return false if run.instr_text
         return false if run.sym

data/lib/uniword/builder.rb

@@ -31,6 +31,7 @@ module Uniword
     autoload :NumberingBuilder, "uniword/builder/numbering_builder"
     autoload :ImageBuilder, "uniword/builder/image_builder"
     autoload :CommentBuilder, "uniword/builder/comment_builder"
+    autoload :CommentAnchorer, "uniword/builder/comment_anchorer"
     autoload :TocBuilder, "uniword/builder/toc_builder"
     autoload :ListBuilder, "uniword/builder/list_builder"
     autoload :ThemeBuilder, "uniword/builder/theme_builder"

data/lib/uniword/cli/fonts_cli.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Uniword
+  # Fonts subcommands for Uniword CLI.
+  #
+  # Rewrites font families inside document content — the CLI equivalent
+  # of Word's Home → Replace → Replace Fonts, across styles, defaults,
+  # body, headers/footers, notes, comments, and numbering in one pass.
+  class FontsCLI < Thor
+    include CLIHelpers
+
+    desc "replace INPUT OUTPUT", "Replace a font family throughout a document"
+    long_desc <<~DESC
+      Replace one font family with another across styles and defaults,
+      body content, headers/footers, notes, comments, and numbering —
+      Word's Replace Fonts dialog as a one-shot CLI command. Theme font
+      references are untouched; use 'uniword theme fonts' for those.
+
+      Examples:
+        $ uniword fonts replace input.docx output.docx --from Calibri --to Carlito
+    DESC
+    option :from, type: :string, required: true,
+                  desc: "Font family to replace (exact match)"
+    option :to, type: :string, required: true,
+                desc: "Replacement font family"
+    option :verbose, aliases: "-v", desc: "Verbose output", type: :boolean,
+                     default: false
+    def replace(input_path, output_path)
+      say "Loading document #{input_path}...", :green if options[:verbose]
+
+      count = replace_in_file(input_path, output_path)
+      say "Replaced #{count} font reference(s) " \
+          "('#{options[:from]}' → '#{options[:to]}') in #{output_path}",
+          :green
+    rescue Uniword::Error => e
+      handle_error(e)
+    rescue StandardError => e
+      handle_error(e, verbose: options[:verbose])
+    end
+
+    private
+
+    def replace_in_file(input_path, output_path)
+      doc = load_document(input_path)
+      count = doc.replace_font(from: options[:from], to: options[:to])
+      doc.save(output_path)
+      count
+    end
+  end
+end

data/lib/uniword/cli/main.rb

@@ -91,6 +91,35 @@ module Uniword
       handle_error(e)
     end
 
+    desc "repair INPUT OUTPUT", "Repair a document and report the fixes"
+    long_desc <<~DESC
+      Load a document, run the save-time Reconciler over it, and write a
+      repaired copy: dangling references are stripped, missing required
+      parts are rebuilt, relationship issues are normalized, and the
+      result is verified by the write-time integrity gate. Every repair
+      is reported (code, part, message).
+
+      Examples:
+        $ uniword repair broken.docx fixed.docx
+        $ uniword repair broken.docx fixed.docx --verbose
+    DESC
+    option :verbose, aliases: "-v", desc: "Show every applied fix",
+                     type: :boolean, default: false
+    def repair(input_path, output_path)
+      say "Loading #{input_path}...", :green
+
+      fixes = repair_file(input_path, output_path)
+      report_repairs(fixes)
+      say "Saved to #{output_path}", :green
+    rescue Uniword::ValidationError => e
+      say "Repair failed — the document has issues the Reconciler " \
+          "cannot fix:", :red
+      e.issues.each { |issue| say "  #{issue.code}: #{issue.message}", :red }
+      exit 1
+    rescue Uniword::Error, StandardError => e
+      handle_error(e)
+    end
+
     desc "validate FILE", "Validate document structure"
     long_desc <<~DESC
       Validate a document's structure and check for common issues.
@@ -107,20 +136,15 @@ module Uniword
       doc = load_document(path)
       say "File format is valid", :green
 
-      if doc.valid?
-        say "Document structure is valid", :green
-      else
-        say "Document has structural issues", :yellow
-      end
-
-      if doc.paragraphs.any? || doc.tables.any?
-        say "Document contains content", :green
-      else
-        say "Document appears to be empty", :yellow
-      end
+      issues = Uniword::Validation::Engine.run(
+        Uniword::Validation::Rules::ModelContext.new(doc),
+      )
+      report_validation_issues(issues)
+      report_content_presence(doc)
 
       display_detailed_validation(doc) if options[:verbose]
       say "\nValidation complete!", :green
+      exit 1 if issues.any?(&:error?)
     rescue Uniword::Error => e
       handle_error(e)
     rescue StandardError => e
@@ -363,6 +387,15 @@ module Uniword
     desc "theme SUBCOMMAND", "Manage document themes"
     subcommand "theme", ThemeCLI
 
+    desc "fonts SUBCOMMAND", "Replace font families in documents"
+    subcommand "fonts", FontsCLI
+
+    desc "page SUBCOMMAND", "Page setup (size, orientation, margins)"
+    subcommand "page", PageCLI
+
+    desc "styles SUBCOMMAND", "Inspect document styles"
+    subcommand "styles", StylesCLI
+
     desc "styleset SUBCOMMAND", "Manage document StyleSets"
     subcommand "styleset", StyleSetCLI
 
@@ -399,8 +432,50 @@ module Uniword
     desc "protect SUBCOMMAND", "Manage document protection"
     subcommand "protect", ProtectCLI
 
+    # Fix codes that are routine normalization, applied on every save
+    # regardless of document health (package structure, properties,
+    # default styles) — not evidence of a broken document.
+    BASELINE_FIX_CODES = %w[R1 R6 R7 R8 R14 R24].freeze
+
     private
 
+    # Report substantive repairs; routine normalization is summarized
+    # separately so a healthy document does not look "repaired".
+    def report_repairs(fixes)
+      substantive = substantive_fixes(fixes)
+      baseline = fixes.size - substantive.size
+
+      return report_consistent(baseline) if substantive.empty?
+
+      say "Applied #{substantive.size} repair(s):", :green
+      summarize_fixes(substantive)
+      say "(plus #{baseline} routine normalization(s))", :cyan
+      substantive.each { |fix| say "  #{fix}" } if options[:verbose]
+    end
+
+    def substantive_fixes(fixes)
+      fixes.reject { |fix| BASELINE_FIX_CODES.include?(fix.code) }
+    end
+
+    def report_consistent(baseline)
+      say "No repairs needed — document consistent " \
+          "(#{baseline} routine normalization(s)).", :green
+    end
+
+    # Load, reconcile, and save; return the reconciler's fix report.
+    def repair_file(input_path, output_path)
+      package = Docx::Package.from_file(input_path)
+      package.to_file(output_path)
+      package.applied_fixes
+    end
+
+    # Print a one-line count per fix code (full list with --verbose).
+    def summarize_fixes(fixes)
+      fixes.group_by(&:code).sort.each do |code, group|
+        say "  #{code} ×#{group.size}: #{group.first.message}"
+      end
+    end
+
     def display_verbose_info(doc)
       say "\nDetailed Information:", :cyan
 
@@ -421,6 +496,30 @@ module Uniword
       end
     end
 
+    # Print validation issues grouped by severity.
+    def report_validation_issues(issues)
+      errors = issues.select(&:error?)
+      if errors.empty?
+        say "Document structure is valid", :green
+      else
+        say "Document has structural errors:", :red
+        errors.each { |issue| say "  [#{issue.code}] #{issue.message}", :red }
+      end
+
+      issues.select(&:warning?).each do |issue|
+        say "  [#{issue.code}] #{issue.message}", :yellow
+      end
+    end
+
+    # Print whether the document contains any content.
+    def report_content_presence(doc)
+      if doc.paragraphs.any? || doc.tables.any?
+        say "Document contains content", :green
+      else
+        say "Document appears to be empty", :yellow
+      end
+    end
+
     def display_detailed_validation(doc)
       say "\nDetailed Validation:", :cyan