uniword 1.2.5 → 1.3.0

data/lib/uniword/docx/part_collection.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    # Keyed collection of Docx::Part objects.
+    #
+    # Backs +chart_parts+ (keyed by relationship id) and +embeddings+
+    # (keyed by relationship target). Keeps the legacy Hash-like
+    # access patterns working: assignment accepts Part objects, the
+    # former raw hashes ({ xml:, target: }) and raw content Strings,
+    # normalizing them into Part objects.
+    #
+    # @example
+    #   parts = PartCollection.new(:r_id)
+    #   parts["rIdChart1"] = { xml: "...", target: "charts/chart1.xml" }
+    #   parts.values.first[:target] # => "charts/chart1.xml"
+    class PartCollection
+      include Enumerable
+
+      # @param key_attribute [Symbol] part attribute serving as the
+      #   collection key (:r_id for charts, :target for embeddings)
+      # @param part_class [Class] Part subclass used to wrap raw values
+      def initialize(key_attribute, part_class)
+        @key_attribute = key_attribute
+        @part_class = part_class
+        @parts = {}
+      end
+
+      # @param key [String] collection key (rId or target)
+      # @return [Part, nil]
+      def [](key)
+        @parts[key]
+      end
+
+      # Store a part, normalizing raw hashes and raw content.
+      #
+      # @param key [String] collection key
+      # @param value [Part, Hash, String]
+      def []=(key, value)
+        @parts[key] = wrap(key, value)
+      end
+
+      # Iterate over [key, Part] pairs.
+      def each(&block)
+        @parts.each(&block)
+      end
+
+      # Iterate over collection keys.
+      def each_key(&block)
+        @parts.each_key(&block)
+      end
+
+      # Iterate over stored parts.
+      def each_value(&block)
+        @parts.each_value(&block)
+      end
+
+      # @return [Array<Part>]
+      def values
+        @parts.values
+      end
+
+      # @return [Array<String>]
+      def keys
+        @parts.keys
+      end
+
+      # @return [Integer]
+      def size
+        @parts.size
+      end
+
+      # @return [Boolean]
+      def empty?
+        @parts.empty?
+      end
+
+      # @return [Boolean]
+      def key?(key)
+        @parts.key?(key)
+      end
+
+      # @return [Part, nil] the removed part
+      def delete(key)
+        @parts.delete(key)
+      end
+
+      # Replace the whole collection from a Hash (or another
+      # PartCollection); nil clears it.
+      #
+      # @param value [Hash, PartCollection, nil]
+      # @return [void]
+      def replace_all(value)
+        @parts.clear
+        return if value.nil?
+
+        value.each { |key, part| self[key] = part }
+      end
+
+      private
+
+      def wrap(key, value)
+        case value
+        when Part
+          value
+        when Hash
+          @part_class.new(
+            target: value[:target], content: value[:content] || value[:xml],
+          ).tap { |part| assign_key(part, key) }
+        else
+          @part_class.new(content: value).tap { |part| assign_key(part, key) }
+        end
+      end
+
+      def assign_key(part, key)
+        case @key_attribute
+        when :r_id then part.r_id ||= key.to_s
+        when :target then part.target ||= key.to_s
+        end
+      end
+    end
+  end
+end

data/lib/uniword/docx/reconciler/body.rb

@@ -21,7 +21,8 @@ module Uniword
               doc_grid: Wordprocessingml::PageDefaults.default_doc_grid,
             )
             record_fix(FixCodes::SECTION_PROPERTIES_DEFAULTED,
-                       "Added default section properties with US Letter page size")
+                       "Added default section properties with US Letter page size",
+                       part: "word/document.xml")
             return
           end
 
@@ -41,70 +42,82 @@ module Uniword
           end
           if fixed
             record_fix(FixCodes::SECTION_PROPERTIES_DEFAULTED,
-                       "Filled missing pgSz/pgMar/cols in existing section properties")
+                       "Filled missing pgSz/pgMar/cols in existing section properties",
+                       part: "word/document.xml")
           end
         end
 
         def reconcile_headers_footers
+          parts = package.document&.header_footer_parts
           ignorable = Ooxml::Types::McIgnorable.new(FULL_IGNORABLE)
-          set_header_footer_ignorable(package.document&.headers, ignorable)
-          set_header_footer_ignorable(package.document&.footers, ignorable)
 
-          unless allocator
-            rsid = generate_rsid
-            backfill_header_footer_parts(package.document&.headers, rsid, "hdr")
-            backfill_header_footer_parts(package.document&.footers, rsid, "ftr")
+          parts&.each do |part|
+            next unless part.content
+            next if part.loaded?
 
-            parts = package.document&.header_footer_parts
-            parts&.each_with_index do |part, pidx|
-              backfill_paragraphs(part[:content].paragraphs, rsid, "hfp:#{pidx}")
-            end
+            part.content.mc_ignorable = ignorable
+          end
+
+          unless builder_managed?
+            backfill_header_footer_paragraphs(parts, generate_rsid)
           end
 
-          wire_builder_headers_footers
+          wire_header_footer_parts
         end
 
         private
 
-        def set_header_footer_ignorable(parts, ignorable)
-          return unless parts
-
-          parts.each_value { |part| part.mc_ignorable = ignorable }
-        end
-
-        def backfill_header_footer_parts(parts, rsid, prefix)
+        # Assign rsid/paraId defaults to header/footer paragraphs
+        # (legacy, non-builder-managed path only). Seeds preserve the
+        # historic per-kind ("hdr:N"/"ftr:N") and per-store ("hfp:N")
+        # schemes so generated IDs stay stable across the unified store.
+        def backfill_header_footer_paragraphs(parts, rsid)
           return unless parts
 
-          parts.each_with_index do |(_, part), pidx|
-            backfill_paragraphs(part.paragraphs, rsid, "#{prefix}:#{pidx}")
+          fresh_counts = Hash.new(0)
+          parts.each_with_index do |part, pidx|
+            next unless part.content
+
+            if part.loaded?
+              backfill_paragraphs(part.content.paragraphs, rsid, "hfp:#{pidx}")
+            else
+              abbrev = part.kind == :footer ? "ftr" : "hdr"
+              idx = fresh_counts[part.kind]
+              fresh_counts[part.kind] += 1
+              backfill_paragraphs(part.content.paragraphs, rsid,
+                                  "#{abbrev}:#{idx}")
+            end
           end
         end
 
-        HEADER_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header"
-        FOOTER_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer"
-
-        # Wire builder-path headers/footers into document_rels and sectPr
-        # during reconciliation so referential integrity checks see valid rIds.
-        def wire_builder_headers_footers
+        # Wire builder-added (fresh) header/footer parts into
+        # document_rels and sectPr during reconciliation — the single
+        # wiring implementation. Loaded parts keep the relationships
+        # and section references they arrived with. rIds come from the
+        # allocator, the single rId authority.
+        def wire_header_footer_parts
           doc = package.document
           return unless doc&.body
-          return unless doc.headers || doc.footers
+
+          parts = doc.header_footer_parts
+          return if parts.nil? || parts.empty?
 
           rels = package.document_rels
           return unless rels
 
-          counter = 0
-          wire_parts_to_rels(doc.headers, rels, HEADER_REL_TYPE,
-                             "header", counter) do |type, r_id|
-            wire_sect_pr_reference(doc, :header, type, r_id)
-          end
+          wired = false
+          parts.each do |part|
+            next if part.loaded? || part.target.nil?
 
-          counter = 0
-          wire_parts_to_rels(doc.footers, rels, FOOTER_REL_TYPE,
-                             "footer", counter) do |type, r_id|
-            wire_sect_pr_reference(doc, :footer, type, r_id)
+            r_id = allocator.alloc_rid(target: part.target,
+                                       type: part.rel_type)
+            part.r_id = r_id
+            wire_sect_pr_reference(doc, part.kind, part.type, r_id) if part.type
+            wired = true
           end
 
+          return unless wired
+
           # Clear element_order so header/footer references serialize correctly.
           # Ordered mode only outputs elements in element_order; the template's
           # order may not include newly-added references.
@@ -112,33 +125,6 @@ module Uniword
           sect_pr.element_order = nil if sect_pr&.element_order
         end
 
-        def wire_parts_to_rels(parts, rels, rel_type, file_prefix, counter)
-          return unless parts && !parts.empty?
-
-          parts.each_key do |type|
-            counter += 1
-            target = "#{file_prefix}#{counter}.xml"
-            r_id = if allocator
-                     allocator.alloc_rid(target: target, type: rel_type)
-                   else
-                     find_or_create_rel(rels, rel_type, target)
-                   end
-            yield type, r_id
-          end
-        end
-
-        def find_or_create_rel(rels, rel_type, target)
-          existing = rels.relationships.find { |r| r.target == target }
-          return existing.id if existing
-
-          r_id = Ooxml::Relationships::PackageRelationships
-            .next_available_rid(rels)
-          rels.relationships << Ooxml::Relationships::Relationship.new(
-            id: r_id, type: rel_type, target: target,
-          )
-          r_id
-        end
-
         def wire_sect_pr_reference(doc, kind, type, r_id)
           sect_pr = doc.body.section_properties
           return unless sect_pr
@@ -169,14 +155,15 @@ module Uniword
           doc = package.document
           set_mc_ignorable(doc, prefixes: FULL_IGNORABLE)
 
-          record_fix(FixCodes::MC_IGNORABLE, "Added mc:Ignorable to document body")
+          record_fix(FixCodes::MC_IGNORABLE, "Added mc:Ignorable to document body",
+                     part: "word/document.xml")
 
           body = doc.body
           rsid = generate_rsid
 
           body.paragraphs.each_with_index do |para, idx|
             strip_empty_runs(para)
-            next if allocator
+            next if builder_managed?
 
             para.rsid_r ||= rsid
             para.rsid_r_default ||= "00000000"
@@ -184,7 +171,11 @@ module Uniword
             para.text_id ||= "77777777"
           end
 
-          record_fix(FixCodes::PARAGRAPH_BACKFILL, "Assigned rsid and paraId to paragraphs") unless allocator
+          unless builder_managed?
+            record_fix(FixCodes::PARAGRAPH_BACKFILL,
+                       "Assigned rsid and paraId to paragraphs",
+                       part: "word/document.xml")
+          end
 
           sect_pr = body.section_properties
           return unless sect_pr

data/lib/uniword/docx/reconciler/fix.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class Reconciler
+      # A single repair applied by the Reconciler during save.
+      #
+      # Immutable value object exposed as the reconciliation report via
+      # `Package#applied_fixes` after a save. The Reconciler stays the only
+      # mutating pass; this report is a by-product value, not a global.
+      #
+      # @example Inspect fixes after save
+      #   package.to_file("out.docx")
+      #   package.applied_fixes.each do |fix|
+      #     puts "#{fix.code} [#{fix.part}] #{fix.message}"
+      #   end
+      class Fix
+        # @return [String] Fix code (see Reconciler::FixCodes)
+        attr_reader :code
+
+        # @return [String] Human-readable description of the repair
+        attr_reader :message
+
+        # @return [String, nil] Package part the repair applies to
+        attr_reader :part
+
+        # Create a fix record.
+        #
+        # @param code [String] Fix code (a FixCodes constant value)
+        # @param message [String] Human-readable description of the repair
+        # @param part [String, nil] Package part the repair applies to
+        def initialize(code:, message:, part: nil)
+          @code = code
+          @message = message
+          @part = part
+        end
+
+        # @return [String] Compact single-line representation
+        def to_s
+          location = part ? " [#{part}]" : ""
+          "#{code}#{location}: #{message}"
+        end
+      end
+    end
+  end
+end

data/lib/uniword/docx/reconciler/fix_codes.rb

@@ -7,14 +7,15 @@ module Uniword
       #
       # Every `record_fix` call site references a constant from this module
       # instead of a bare string literal. Adding a new fix category means
-      # adding one constant here, not hunting for the next free letter.
+      # adding one constant here with the next free code.
       #
-      # Wire format is preserved — external validation rules and audit-log
-      # consumers that pattern-match on "R1".."R16" continue to work.
-      #
-      # Known debt: R10 is overloaded for several distinct concerns
-      # (note defs, table structure, style defaults, dangling refs).
-      # Splitting requires consumer coordination.
+      # One code per concern: each constant has a unique, self-describing
+      # wire value. Codes "R1".."R16" are frozen — external validation rules
+      # (lib/uniword/validation/rules) and audit-log consumers pattern-match
+      # on them, so the original concerns keep their historic codes. Codes
+      # "R17" and up were introduced when the overloaded "R10" (and the
+      # remaining shared codes "R4"/"R11"/"R12"/"R13") were split into
+      # per-concern values.
       module FixCodes
         # Settings / package structure
         MC_IGNORABLE = "R1"
@@ -29,17 +30,12 @@ module Uniword
         CONTENT_TYPES_ASSEMBLED = "R7"
         APP_PROPERTIES_ENSURED = "R8"
 
-        # Notes — pair creation
+        # Notes — pair creation and definition integrity
         NOTE_PAIR_CREATED = "R9"
         NOTE_DEFINITION_CREATED = "R10"
         NOTE_INVALID_TYPE_STRIPPED = "R15"
         NOTE_DUPLICATE_ID_REMOVED = "R16"
 
-        # Notes — referential integrity warnings and removals
-        DANGLING_NOTE_REFERENCE_WARNING = "R9"
-        DANGLING_NOTE_REFERENCE_REMOVED = "R10"
-        DANGLING_HYPERLINK_WARNING = "R9"
-
         # Body
         SECTION_PROPERTIES_DEFAULTED = "R11"
         PARAGRAPH_BACKFILL = "R12"
@@ -48,26 +44,37 @@ module Uniword
         FONT_TABLE_CREATED = "R13"
         CORE_PROPERTIES_REBUILT = "R14"
 
-        # Styles (currently shares R10 with other concerns — see debt note above)
-        STYLE_DEFAULTS_ADDED = "R10"
-        SEMI_HIDDEN_ADDED = "R10"
+        # Referential integrity — dangling-reference repairs (split from
+        # the overloaded R10/R4/R11/R12 codes; one code per concern)
+        DANGLING_NUMBERING_REMOVED = "R17"
+        DANGLING_NOTE_REFERENCE_REMOVED = "R18"
+        DANGLING_STYLE_REFERENCE_REMOVED = "R19"
+        DANGLING_BASED_ON_REMOVED = "R20"
+        DANGLING_HYPERLINK_REMOVED = "R21"
+        DANGLING_HEADER_FOOTER_REMOVED = "R22"
+        DANGLING_DRAWING_REMOVED = "R23"
+        DANGLING_RELATIONSHIP_TARGET_REMOVED = "R32"
+
+        # Referential integrity — literal hyperlink targets promoted to
+        # proper External relationships (repairs Builder.hyperlink output)
+        HYPERLINK_RELATIONSHIP_CREATED = "R31"
+
+        # Styles
+        STYLE_DEFAULTS_ADDED = "R24"
+        SEMI_HIDDEN_ADDED = "R25"
 
-        # Tables (currently shares R10)
-        TABLE_STRUCTURE_RECONCILED = "R10"
-        TABLE_CELL_PR_REORDERED = "R10"
-        TABLE_CELL_DEFAULTS = "R12"
-        TABLE_ROW_GRID_AFTER = "R13"
+        # Tables
+        TABLE_STRUCTURE_RECONCILED = "R26"
+        TABLE_CELL_PR_REORDERED = "R27"
+        TABLE_CELL_DEFAULTS = "R28"
+        TABLE_ROW_GRID_AFTER = "R29"
 
-        # Referential integrity (currently shares R10)
-        DANGLING_STYLE_REFERENCE_REMOVED = "R10"
-        DANGLING_BASED_ON_REMOVED = "R10"
-        DANGLING_NUMBERING_REMOVED = "R4"
-        DANGLING_HYPERLINK_REMOVED = "R10"
-        DANGLING_HEADER_FOOTER_REMOVED = "R11"
-        DANGLING_DRAWING_REMOVED = "R12"
+        # Run cleanup
+        EMPTY_RUNS_STRIPPED = "R30"
 
-        # Run cleanup (currently shares R10)
-        EMPTY_RUNS_STRIPPED = "R10"
+        # Tables — gridCol widths defaulted to equal shares of the
+        # section content width (Word's fallback behavior)
+        TABLE_GRID_COL_WIDTHS_DEFAULTED = "R33"
       end
     end
   end

data/lib/uniword/docx/reconciler/helpers.rb

@@ -85,7 +85,7 @@ module Uniword
           walk_body_paragraphs(package.document.body, &block)
 
           (package.document&.header_footer_parts || []).each do |part|
-            (part[:content]&.paragraphs || []).each(&block)
+            (part.content&.paragraphs || []).each(&block)
           end
         end
 
@@ -295,6 +295,14 @@ module Uniword
           end
         end
 
+        # Package part path of the notes collection for the note type.
+        def notes_part_for(type)
+          case type
+          when :footnote then "word/footnotes.xml"
+          when :endnote  then "word/endnotes.xml"
+          end
+        end
+
         def note_entries_for(notes, type)
           return [] unless notes
 

data/lib/uniword/docx/reconciler/notes.rb

@@ -38,7 +38,8 @@ module Uniword
               )
             end
             record_fix(FixCodes::NOTE_DEFINITION_CREATED,
-                       "Created missing #{type}note definitions for ids=#{missing.join(', ')}")
+                       "Created missing #{type}note definitions for ids=#{missing.join(', ')}",
+                       part: notes_part_for(type))
           end
         end
 
@@ -70,11 +71,13 @@ module Uniword
                                  create_message:, pr_message:)
           if has_pr && !notes
             notes_setter.call(minimal_notes(type))
-            record_fix(FixCodes::NOTE_PAIR_CREATED, create_message)
+            record_fix(FixCodes::NOTE_PAIR_CREATED, create_message,
+                       part: notes_part_for(type))
           elsif notes && !has_pr
             package.settings ||= Wordprocessingml::Settings.new
             assign_note_pr(package.settings, type)
-            record_fix(FixCodes::NOTE_PAIR_CREATED, pr_message)
+            record_fix(FixCodes::NOTE_PAIR_CREATED, pr_message,
+                       part: "word/settings.xml")
           end
 
           current = notes_collection_for(type)
@@ -92,7 +95,7 @@ module Uniword
           strip_empty_runs_from_notes(entries)
           reorder_notes_by_reference(entries, type)
 
-          unless allocator
+          unless builder_managed?
             prefix = type == :footnote ? "fn" : "en"
 
             entries.each_with_index do |entry, eidx|
@@ -182,7 +185,8 @@ module Uniword
           return if stripped.empty?
 
           record_fix(FixCodes::NOTE_INVALID_TYPE_STRIPPED,
-                     "Stripped invalid w:type from #{type}note ids=#{stripped.join(', ')}")
+                     "Stripped invalid w:type from #{type}note ids=#{stripped.join(', ')}",
+                     part: notes_part_for(type))
         end
 
         def deduplicate_note_ids(entries, type)
@@ -200,7 +204,8 @@ module Uniword
           return if dup_ids.empty?
 
           record_fix(FixCodes::NOTE_DUPLICATE_ID_REMOVED,
-                     "Removed duplicate #{type}note ids=#{dup_ids.join(', ')}")
+                     "Removed duplicate #{type}note ids=#{dup_ids.join(', ')}",
+                     part: notes_part_for(type))
         end
 
         def reorder_notes_by_reference(entries, type)
@@ -227,7 +232,9 @@ module Uniword
           structural.each { |e| entries << e }
           reordered.each { |e| entries << e }
 
-          record_fix(FixCodes::NOTE_PAIR_CREATED, "Reordered #{type}notes by first reference in document body")
+          record_fix(FixCodes::NOTE_PAIR_CREATED,
+                     "Reordered #{type}notes by first reference in document body",
+                     part: notes_part_for(type))
         end
 
         def renumber_notes(entries, type)
@@ -255,7 +262,9 @@ module Uniword
             end
           end
 
-          record_fix(FixCodes::NOTE_PAIR_CREATED, "Renumbered #{type}note IDs sequentially (#{id_map.size} changed)")
+          record_fix(FixCodes::NOTE_PAIR_CREATED,
+                     "Renumbered #{type}note IDs sequentially (#{id_map.size} changed)",
+                     part: notes_part_for(type))
         end
 
         def collect_note_reference_order(body, type)