uniword 1.2.5 → 1.3.0

data/lib/uniword/docx/package.rb

@@ -44,7 +44,15 @@ module Uniword
       attribute :custom_properties, Ooxml::CustomProperties
 
       # Custom XML data items (customXml/item*.xml)
-      attr_accessor :custom_xml_items
+      #
+      # @return [Array<CustomXmlItem>, nil]
+      attr_reader :custom_xml_items
+
+      # Assign custom XML items; accepts CustomXmlItem objects and
+      # legacy hashes ({ index:, xml_content:, props_xml:, rels_xml: }).
+      def custom_xml_items=(items)
+        @custom_xml_items = items && items.map { |i| CustomXmlItem.wrap(i) }
+      end
 
       # === Document Parts (word/) ===
       # Main document content (word/document.xml)
@@ -82,9 +90,24 @@ module Uniword
       # Endnotes (word/endnotes.xml)
       attribute :endnotes, Uniword::Wordprocessingml::Endnotes
 
+      # Comments (word/comments.xml)
+      attribute :comments, Uniword::CommentsPart
+
       # Non-serialized attributes (DOCX packaging helpers)
       attr_accessor :chart_parts, :bibliography_sources, :profile
-      attr_accessor :settings_rels, :embeddings
+      attr_accessor :settings_rels, :footnotes_rels, :endnotes_rels
+
+      # OLE/embedded object binaries (word/embeddings/*), keyed by target.
+      #
+      # @return [PartCollection] target => Part
+      def embeddings
+        @embeddings ||= PartCollection.new(:target, Part)
+      end
+
+      # Bulk-assign embeddings (Hash of target => Part/binary; nil clears).
+      def embeddings=(value)
+        embeddings.replace_all(value)
+      end
 
       # Central ID allocator — owns all rId, footnote, bookmark, etc. assignment.
       # Seeded from template rels on load; used by builders during construction.
@@ -98,6 +121,15 @@ module Uniword
       # Paths that have been modified and should not use raw XML passthrough.
       attr_accessor :modified_part_paths
 
+      # Audit trail of repairs applied by the Reconciler during the most
+      # recent save (to_zip_content). Empty before the first save and when
+      # the package needed no repairs.
+      #
+      # @return [Array<Reconciler::Fix>] Fixes from the most recent save
+      def applied_fixes
+        @applied_fixes ||= []
+      end
+
       # Load DOCX package from file
       #
       # @param path [String] Path to .docx file
@@ -162,18 +194,15 @@ module Uniword
           package.custom_xml_items = []
           custom_xml_files.sort_by { |f| f[/item(\d+)/, 1].to_i }.each do |item_path|
             index = item_path[/item(\d+)/, 1].to_i
-            item = {
-              index: index,
-              xml_content: zip_content[item_path]
-            }
-
             props_path = "customXml/itemProps#{index}.xml"
-            item[:props_xml] = zip_content[props_path] if zip_content[props_path]
-
             rels_path = "customXml/_rels/item#{index}.xml.rels"
-            item[:rels_xml] = zip_content[rels_path] if zip_content[rels_path]
 
-            package.custom_xml_items << item
+            package.custom_xml_items << CustomXmlItem.new(
+              index: index,
+              xml_content: zip_content[item_path],
+              props_xml: zip_content[props_path],
+              rels_xml: zip_content[rels_path],
+            )
           end
         end
 
@@ -266,13 +295,35 @@ module Uniword
           )
         end
 
+        # Parse Comments
+        if zip_content["word/comments.xml"]
+          package.comments = Uniword::CommentsPart.from_xml(
+            zip_content["word/comments.xml"]
+          )
+        end
+
+        # Parse note part relationships (r:id refs inside notes, e.g.
+        # hyperlinks in footnotes) so they survive the round-trip.
+        if zip_content["word/_rels/footnotes.xml.rels"]
+          package.footnotes_rels =
+            Ooxml::Relationships::PackageRelationships.from_xml(
+              zip_content["word/_rels/footnotes.xml.rels"]
+            )
+        end
+
+        if zip_content["word/_rels/endnotes.xml.rels"]
+          package.endnotes_rels =
+            Ooxml::Relationships::PackageRelationships.from_xml(
+              zip_content["word/_rels/endnotes.xml.rels"]
+            )
+        end
+
         # Parse Header and Footer parts
         extract_header_footer_parts(zip_content, package)
 
         # Parse Chart parts
         chart_files = zip_content.keys.grep(%r{^word/charts/chart\d+\.xml$})
         if chart_files.any? && package.document_rels
-          package.document.chart_parts ||= {}
           chart_files.each do |chart_path|
             chart_target = chart_path.sub("word/", "")
             rel = package.document_rels.relationships.find do |r|
@@ -312,7 +363,8 @@ module Uniword
 
         return if header_files.empty? && footer_files.empty?
 
-        package.document.header_footer_parts ||= []
+        store = package.document.header_footer_parts
+        ref_types = header_footer_reference_types(package.document)
 
         header_files.sort.each do |path|
           target = path.sub("word/", "")
@@ -322,13 +374,15 @@ module Uniword
           end
           next unless rel
 
-          package.document.header_footer_parts << {
+          store << HeaderFooterPart.new(
+            kind: :header,
             r_id: rel.id,
             target: target,
             rel_type: rel.type,
-            content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml",
+            type: ref_types[rel.id],
             content: Uniword::Wordprocessingml::Header.from_xml(zip_content[path]),
-          }
+            loaded: true,
+          )
         end
 
         footer_files.sort.each do |path|
@@ -339,14 +393,45 @@ module Uniword
           end
           next unless rel
 
-          package.document.header_footer_parts << {
+          store << HeaderFooterPart.new(
+            kind: :footer,
             r_id: rel.id,
             target: target,
             rel_type: rel.type,
-            content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml",
+            type: ref_types[rel.id],
             content: Uniword::Wordprocessingml::Footer.from_xml(zip_content[path]),
-          }
+            loaded: true,
+          )
+        end
+      end
+
+      # Map relationship id => sectPr reference type
+      # ("default"/"first"/"even") from every section properties
+      # element (body-level and paragraph-level).
+      def self.header_footer_reference_types(document)
+        types = {}
+        section_properties_of(document).each do |sect_pr|
+          (sect_pr.header_references || []).each do |ref|
+            types[ref.r_id] = ref.type if ref.r_id
+          end
+          (sect_pr.footer_references || []).each do |ref|
+            types[ref.r_id] = ref.type if ref.r_id
+          end
+        end
+        types
+      end
+
+      def self.section_properties_of(document)
+        body = document.body
+        return [] unless body
+
+        sect_prs = []
+        sect_prs << body.section_properties if body.section_properties
+        (body.paragraphs || []).each do |para|
+          sect_pr = para.properties&.section_properties
+          sect_prs << sect_pr if sect_pr
         end
+        sect_prs
       end
 
       # Extract image files from word/media/ directory in DOCX
@@ -375,14 +460,13 @@ module Uniword
                          else "image/#{ext}"
                          end
 
-          r_id = if package.allocator
-                   package.allocator.alloc_rid(
-                     target: "media/#{filename}",
-                     type: IdAllocator::IMAGE_REL_TYPE,
-                   )
-                 else
-                   "rId#{package.document.image_parts.size + 1}"
-                 end
+          # Key the part by the rId the loaded document rels assign to
+          # this target, so downstream consumers (MHTML rendering, image
+          # manager) resolve r:embed references correctly. Media with no
+          # document-level rel (e.g. theme-only images) gets a synthetic
+          # key; it never becomes a relationship.
+          r_id = loaded_image_rid(package, filename) ||
+            next_synthetic_image_key(package)
 
           binary_data = if zip_path
                           read_binary_from_zip(zip_path, media_path)
@@ -398,6 +482,25 @@ module Uniword
         end
       end
 
+      # The rId a loaded document relationship assigns to
+      # "media/<filename>", or nil when no image rel targets it.
+      def self.loaded_image_rid(package, filename)
+        image_type = Ooxml::PartRegistry.find_by_key(:image).rel_type
+        rel = package.document_rels&.relationships&.find do |r|
+          r.target == "media/#{filename}" && r.type.to_s == image_type
+        end
+        rel&.id
+      end
+
+      # Synthetic image-part key that cannot collide with a loaded
+      # relationship id or an already-keyed image part.
+      def self.next_synthetic_image_key(package)
+        taken = package.document_rels&.relationships&.map(&:id) || []
+        n = package.document.image_parts.size + 1
+        n += 1 while taken.include?("rId#{n}")
+        "rId#{n}"
+      end
+
       # Read binary data directly from ZIP file without UTF-8 encoding
       def self.read_binary_from_zip(zip_path, entry_path)
         require "zip"
@@ -410,7 +513,14 @@ module Uniword
       end
 
       # Save document to file (class method for DocumentWriter compatibility)
-      def self.to_file(document, path, profile: nil)
+      #
+      # @param document [Wordprocessingml::DocumentRoot] Document to save
+      # @param path [String] Output file path
+      # @param profile [Profile, nil] Reconciliation profile
+      # @param validate [Boolean, nil] Run the package integrity gate before
+      #   writing; nil falls back to Uniword.configuration.validate_on_save
+      # @return [void]
+      def self.to_file(document, path, profile: nil, validate: nil)
         package = new
         package.document = document
         package.profile = profile || Profile.defaults
@@ -421,7 +531,7 @@ module Uniword
         package.settings ||= Uniword::Wordprocessingml::Settings.new
         package.font_table ||= Uniword::Wordprocessingml::FontTable.new
         package.web_settings ||= Uniword::Wordprocessingml::WebSettings.new
-        package.to_file(path)
+        package.to_file(path, validate: validate)
       end
 
       # Populate the allocator from all existing template data.
@@ -430,6 +540,20 @@ module Uniword
         @allocator = IdAllocator.populate_from_package(self)
       end
 
+      # Guarantee the single rId authority before reconciliation: reuse
+      # the package's allocator (loaded/builder-seeded) or start one,
+      # then seed it from the package's current relationships. Seeding
+      # preserves loaded rIds verbatim; earlier builder allocations keep
+      # their ids — a seeded rel whose id collides is reallocated
+      # deterministically (IdAllocator#seed_from_rels).
+      def prepare_allocator
+        self.allocator ||= IdAllocator.new
+        allocator.seed_from_rels(package_rels&.relationships,
+                                 scope: :package)
+        allocator.seed_from_rels(document_rels&.relationships)
+        allocator
+      end
+
       # Extract media files from word/theme/media/ directory
       def self.extract_theme_media(zip_content)
         media = {}
@@ -449,14 +573,31 @@ module Uniword
       end
 
       # Save package to file
-      def to_file(path)
-        zip_content = to_zip_content
+      #
+      # @param path [String] Output file path
+      # @param validate [Boolean, nil] Run the package integrity gate before
+      #   writing; nil falls back to Uniword.configuration.validate_on_save
+      # @return [void]
+      # @raise [Uniword::ValidationError] when the gate is enabled and the
+      #   generated package content is invalid
+      def to_file(path, validate: nil)
+        zip_content = to_zip_content(validate: validate)
         packager = Infrastructure::ZipPackager.new
         packager.package(zip_content, path)
       end
 
       # Generate ZIP content hash
-      def to_zip_content
+      #
+      # Runs the Reconciler (the only mutating pass), records its repair
+      # report on #applied_fixes, and — unless validation is disabled —
+      # refuses invalid output via the PackageIntegrityChecker gate.
+      #
+      # @param validate [Boolean, nil] Run the package integrity gate;
+      #   nil falls back to Uniword.configuration.validate_on_save
+      # @return [Hash] File paths => content
+      # @raise [Uniword::ValidationError] when the gate is enabled and the
+      #   generated package content is invalid
+      def to_zip_content(validate: nil)
         content = {}
 
         self.content_types ||= self.class.minimal_content_types
@@ -467,15 +608,28 @@ module Uniword
         self.font_table ||= Uniword::Wordprocessingml::FontTable.new
         self.web_settings ||= Uniword::Wordprocessingml::WebSettings.new
 
-        Reconciler.new(self,
-                       profile: profile || Profile.defaults,
-                       allocator: allocator).reconcile
+        # An allocator carried into the save (builder-managed document
+        # or loaded package) selects light-touch repairs; documents
+        # without one get the full normalization repertoire. rIds flow
+        # through the allocator either way.
+        builder_managed = !allocator.nil?
+        prepare_allocator
+
+        reconciler = Reconciler.new(self,
+                                    profile: profile || Profile.defaults,
+                                    allocator: allocator,
+                                    builder_managed: builder_managed)
+        reconciler.reconcile
+        @applied_fixes = reconciler.applied_fixes
+        log_applied_fixes
 
         inject_part_relationships(content, content_types, package_rels, document_rels)
         serialize_package_parts(content, content_types, package_rels, document_rels)
 
         # OOXML requires [Content_Types].xml as the first ZIP entry.
         reorder_content_hash(content)
+
+        enforce_package_integrity(content, validate)
         content
       end
 
@@ -541,6 +695,40 @@ module Uniword
         basename = File.basename(doc_path)
         File.join(dir, "_rels", "#{basename}.rels")
       end
+
+      private
+
+      # Log each applied fix via Uniword.logger when policy allows.
+      #
+      # @return [void]
+      def log_applied_fixes
+        return if @applied_fixes.empty?
+        return unless Uniword.configuration.log_save_fixes
+
+        @applied_fixes.each do |fix|
+          Uniword.logger&.info { "Reconciler fix #{fix}" }
+        end
+      end
+
+      # Write-time integrity gate: refuse invalid package content.
+      #
+      # @param content [Hash] File paths => content
+      # @param validate [Boolean, nil] explicit override; nil reads policy
+      # @return [void]
+      # @raise [Uniword::ValidationError] listing all integrity issues
+      def enforce_package_integrity(content, validate)
+        validate = Uniword.configuration.validate_on_save if validate.nil?
+        return unless validate
+
+        issues = PackageIntegrityChecker.new.check(content)
+        return if issues.empty?
+
+        raise Uniword::ValidationError.new(
+          self,
+          issues.map { |issue| "#{issue.code} (#{issue.part}): #{issue.message}" },
+          issues: issues,
+        )
+      end
     end
   end
 end

data/lib/uniword/docx/package_defaults.rb

@@ -15,6 +15,21 @@ module Uniword
 
       # Class methods for package construction
       module ClassMethods
+        # Part kinds in a minimal [Content_Types].xml, emission order.
+        MINIMAL_CT_DEFAULT_PARTS = %i[rels xml].freeze
+        MINIMAL_CT_OVERRIDE_PARTS =
+          %i[document styles font_table settings web_settings
+             app_properties core_properties].freeze
+
+        # Part kinds in a minimal _rels/.rels, in rId order.
+        MINIMAL_PACKAGE_REL_PARTS =
+          %i[document core_properties app_properties].freeze
+
+        # Part kinds in a minimal word/_rels/document.xml.rels,
+        # in rId order.
+        MINIMAL_DOCUMENT_REL_PARTS =
+          %i[styles settings web_settings font_table].freeze
+
         # Copy parts from document to package for round-trip preservation
         def copy_document_parts_to_package(document, package)
           return unless document.is_a?(Uniword::Wordprocessingml::DocumentRoot)
@@ -30,9 +45,21 @@ module Uniword
           package.document_rels = document.document_rels if document.document_rels
           package.theme_rels = document.theme_rels if document.theme_rels
           package.package_rels = document.package_rels if document.package_rels
+          if document.settings_rels
+            package.settings_rels = document.settings_rels
+          end
+          if document.footnotes_rels
+            package.footnotes_rels = document.footnotes_rels
+          end
+          if document.endnotes_rels
+            package.endnotes_rels = document.endnotes_rels
+          end
           package.content_types = document.content_types if document.content_types
           package.footnotes = document.footnotes if document.footnotes
           package.endnotes = document.endnotes if document.endnotes
+          if document.comments.is_a?(Uniword::CommentsPart)
+            package.comments = document.comments
+          end
           package.allocator = document.allocator if document.allocator
 
           package.numbering = document.numbering_configuration if document.numbering_configuration_loaded?
@@ -46,94 +73,47 @@ module Uniword
         # Create minimal content types for a valid DOCX
         def minimal_content_types
           ct = Uniword::ContentTypes::Types.new
-          ct.defaults ||= []
-          ct.defaults << Uniword::ContentTypes::Default.new(
-            extension: "rels",
-            content_type: "application/vnd.openxmlformats-package.relationships+xml",
-          )
-          ct.defaults << Uniword::ContentTypes::Default.new(
-            extension: "xml",
-            content_type: "application/xml",
-          )
-
-          ct.overrides ||= []
-          ct.overrides << Uniword::ContentTypes::Override.new(
-            part_name: "/word/document.xml",
-            content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml",
-          )
-          ct.overrides << Uniword::ContentTypes::Override.new(
-            part_name: "/word/styles.xml",
-            content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml",
-          )
-          ct.overrides << Uniword::ContentTypes::Override.new(
-            part_name: "/word/fontTable.xml",
-            content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.fontTable+xml",
-          )
-          ct.overrides << Uniword::ContentTypes::Override.new(
-            part_name: "/word/settings.xml",
-            content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml",
-          )
-          ct.overrides << Uniword::ContentTypes::Override.new(
-            part_name: "/word/webSettings.xml",
-            content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.webSettings+xml",
-          )
-          ct.overrides << Uniword::ContentTypes::Override.new(
-            part_name: "/docProps/app.xml",
-            content_type: "application/vnd.openxmlformats-officedocument.extended-properties+xml",
-          )
-          ct.overrides << Uniword::ContentTypes::Override.new(
-            part_name: "/docProps/core.xml",
-            content_type: "application/vnd.openxmlformats-package.core-properties+xml",
-          )
+          ct.defaults = MINIMAL_CT_DEFAULT_PARTS.map do |key|
+            defn = Ooxml::PartRegistry.find_by_key(key)
+            Uniword::ContentTypes::Default.new(
+              extension: defn.extension,
+              content_type: defn.content_type,
+            )
+          end
+          ct.overrides = MINIMAL_CT_OVERRIDE_PARTS.map do |key|
+            defn = Ooxml::PartRegistry.find_by_key(key)
+            Uniword::ContentTypes::Override.new(
+              part_name: defn.part_name,
+              content_type: defn.content_type,
+            )
+          end
           ct
         end
 
         # Create minimal package relationships for a valid DOCX
         def minimal_package_rels
-          rels = Ooxml::Relationships::PackageRelationships.new
-          rels.relationships ||= []
-          rels.relationships << Ooxml::Relationships::Relationship.new(
-            id: "rId1",
-            type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument",
-            target: "word/document.xml",
-          )
-          rels.relationships << Ooxml::Relationships::Relationship.new(
-            id: "rId2",
-            type: "http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties",
-            target: "docProps/core.xml",
-          )
-          rels.relationships << Ooxml::Relationships::Relationship.new(
-            id: "rId3",
-            type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties",
-            target: "docProps/app.xml",
-          )
-          rels
+          build_minimal_rels(MINIMAL_PACKAGE_REL_PARTS)
         end
 
         # Create minimal document relationships for a valid DOCX
         def minimal_document_rels
+          build_minimal_rels(MINIMAL_DOCUMENT_REL_PARTS)
+        end
+
+        private
+
+        # Build a Relationships part with sequential rIds (rId1..rIdN)
+        # for the given registry part keys, in the given order.
+        def build_minimal_rels(part_keys)
           rels = Ooxml::Relationships::PackageRelationships.new
-          rels.relationships ||= []
-          rels.relationships << Ooxml::Relationships::Relationship.new(
-            id: "rId1",
-            type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles",
-            target: "styles.xml",
-          )
-          rels.relationships << Ooxml::Relationships::Relationship.new(
-            id: "rId2",
-            type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings",
-            target: "settings.xml",
-          )
-          rels.relationships << Ooxml::Relationships::Relationship.new(
-            id: "rId3",
-            type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/webSettings",
-            target: "webSettings.xml",
-          )
-          rels.relationships << Ooxml::Relationships::Relationship.new(
-            id: "rId4",
-            type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable",
-            target: "fontTable.xml",
-          )
+          rels.relationships = part_keys.each_with_index.map do |key, idx|
+            defn = Ooxml::PartRegistry.find_by_key(key)
+            Ooxml::Relationships::Relationship.new(
+              id: "rId#{idx + 1}",
+              type: defn.rel_type,
+              target: defn.target,
+            )
+          end
           rels
         end
       end