uniword 1.2.5 → 1.4.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,40 @@ 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 :profile
+      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
+
+      # Raw passthrough parts no registry definition models, keyed by
+      # package path ("docProps/meta.xml", "word/glossary/document.xml",
+      # ...). Carried byte-for-byte from load to save — see
+      # PartLoader::RawPartLoader for claiming and
+      # PackageSerialization#serialize_raw_parts for emission.
+      #
+      # @return [PartCollection] package path => RawPart
+      def raw_parts
+        @raw_parts ||= PartCollection.new(:path, RawPart)
+      end
+
+      # Bulk-assign raw parts (Hash of path => RawPart/hash; nil clears).
+      def raw_parts=(value)
+        raw_parts.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 +137,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
@@ -112,305 +160,28 @@ module Uniword
 
       # Create package from extracted ZIP content
       #
+      # Parts load by iterating Ooxml::PartRegistry.loadable and
+      # dispatching each definition to its Docx::PartLoader strategy —
+      # see PartLoader for the load order and strategy registry.
+      #
       # @param zip_content [Hash] Extracted ZIP files
       # @param zip_path [String, nil] Original ZIP path for binary re-extraction
       # @return [Package] Package object
       def self.from_zip_content(zip_content, zip_path = nil)
         package = new
-
-        # Parse Content Types
-        if zip_content["[Content_Types].xml"]
-          package.content_types = Uniword::ContentTypes::Types.from_xml(
-            zip_content["[Content_Types].xml"]
-          )
-        end
-
-        # Parse Package Relationships
-        if zip_content["_rels/.rels"]
-          package.package_rels = Ooxml::Relationships::PackageRelationships.from_xml(
-            zip_content["_rels/.rels"]
-          )
-        end
-
-        # Find the main document path from officeDocument relationship
-        main_doc_path = find_main_document_path(package.package_rels)
-        main_doc_rels_path = find_document_rels_path(main_doc_path)
-
-        # Parse Document Properties
-        if zip_content["docProps/core.xml"]
-          package.core_properties = Ooxml::CoreProperties.from_xml(
-            zip_content["docProps/core.xml"]
-          )
-        end
-
-        if zip_content["docProps/app.xml"]
-          package.app_properties = Ooxml::AppProperties.from_xml(
-            zip_content["docProps/app.xml"]
-          )
-        end
-
-        # Parse Custom Properties
-        if zip_content["docProps/custom.xml"]
-          package.custom_properties = Ooxml::CustomProperties.from_xml(
-            zip_content["docProps/custom.xml"]
-          )
-        end
-
-        # Parse Custom XML Data items (customXml/item*.xml)
-        custom_xml_files = zip_content.keys.grep(%r{^customXml/item(\d+)\.xml$})
-        if custom_xml_files.any?
-          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
-          end
-        end
-
-        # Parse Document Parts - use dynamic path from package relationships
-        if main_doc_path && zip_content[main_doc_path]
-          package.document = Uniword::Wordprocessingml::DocumentRoot.from_xml(
-            zip_content[main_doc_path]
-          )
-        elsif zip_content["word/document.xml"]
-          package.document = Uniword::Wordprocessingml::DocumentRoot.from_xml(
-            zip_content["word/document.xml"]
-          )
-        end
-
-        if zip_content["word/styles.xml"]
-          package.styles = Uniword::Wordprocessingml::StylesConfiguration.from_xml(
-            zip_content["word/styles.xml"]
-          )
-        end
-
-        if zip_content["word/numbering.xml"]
-          package.numbering = Uniword::Wordprocessingml::NumberingConfiguration.from_xml(
-            zip_content["word/numbering.xml"]
-          )
-        end
-
-        if zip_content["word/settings.xml"]
-          package.settings = Uniword::Wordprocessingml::Settings.from_xml(
-            zip_content["word/settings.xml"]
-          )
-        end
-
-        if zip_content["word/_rels/settings.xml.rels"]
-          package.settings_rels =
-            Ooxml::Relationships::PackageRelationships.from_xml(
-              zip_content["word/_rels/settings.xml.rels"]
-            )
-        end
-
-        if zip_content["word/fontTable.xml"]
-          package.font_table = Uniword::Wordprocessingml::FontTable.from_xml(
-            zip_content["word/fontTable.xml"]
-          )
-        end
-
-        if zip_content["word/webSettings.xml"]
-          package.web_settings = Uniword::Wordprocessingml::WebSettings.from_xml(
-            zip_content["word/webSettings.xml"]
-          )
-        end
-
-        # Parse document relationships - use dynamic path based on main document
-        if main_doc_rels_path && zip_content[main_doc_rels_path]
-          package.document_rels = Ooxml::Relationships::PackageRelationships.from_xml(
-            zip_content[main_doc_rels_path]
-          )
-        elsif zip_content["word/_rels/document.xml.rels"]
-          package.document_rels = Ooxml::Relationships::PackageRelationships.from_xml(
-            zip_content["word/_rels/document.xml.rels"]
-          )
-        end
-
-        # Parse Theme
-        if zip_content["word/theme/theme1.xml"]
-          package.theme = Drawingml::Theme.from_xml(
-            zip_content["word/theme/theme1.xml"]
-          )
-
-          theme_media = extract_theme_media(zip_content)
-          package.theme.media_files = theme_media if theme_media.any?
-        end
-
-        if zip_content["word/theme/_rels/theme1.xml.rels"]
-          package.theme_rels = Ooxml::Relationships::PackageRelationships.from_xml(
-            zip_content["word/theme/_rels/theme1.xml.rels"]
-          )
-        end
-
-        # Parse Footnotes
-        if zip_content["word/footnotes.xml"]
-          package.footnotes = Uniword::Wordprocessingml::Footnotes.from_xml(
-            zip_content["word/footnotes.xml"]
-          )
-        end
-
-        # Parse Endnotes
-        if zip_content["word/endnotes.xml"]
-          package.endnotes = Uniword::Wordprocessingml::Endnotes.from_xml(
-            zip_content["word/endnotes.xml"]
-          )
-        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|
-              r.target == chart_target &&
-                r.type.to_s.include?("officeDocument/2006/relationships/chart")
-            end
-            next unless rel
-
-            package.document.chart_parts[rel.id] = {
-              xml: zip_content[chart_path],
-              target: chart_target
-            }
-          end
-        end
-
-        # Extract image parts from word/media/ directory
-        extract_image_parts(zip_content, package, zip_path)
-
-        # Extract OLE/embedded object binaries from word/embeddings/
-        embedding_files = zip_content.keys.grep(%r{^word/embeddings/.+$})
-        if embedding_files.any?
-          package.embeddings = {}
-          embedding_files.each do |emb_path|
-            target = emb_path.sub("word/", "")
-            package.embeddings[target] = zip_content[emb_path]
-          end
-        end
-
+        PartLoader.load(zip_content, package, zip_path: zip_path)
         package
       end
 
-      def self.extract_header_footer_parts(zip_content, package)
-        return unless package.document && package.document_rels
-
-        header_files = zip_content.keys.grep(%r{^word/header\d+\.xml$})
-        footer_files = zip_content.keys.grep(%r{^word/footer\d+\.xml$})
-
-        return if header_files.empty? && footer_files.empty?
-
-        package.document.header_footer_parts ||= []
-
-        header_files.sort.each do |path|
-          target = path.sub("word/", "")
-          rel = package.document_rels.relationships.find do |r|
-            r.target == target &&
-              r.type.to_s.include?("officeDocument/2006/relationships/header")
-          end
-          next unless rel
-
-          package.document.header_footer_parts << {
-            r_id: rel.id,
-            target: target,
-            rel_type: rel.type,
-            content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml",
-            content: Uniword::Wordprocessingml::Header.from_xml(zip_content[path]),
-          }
-        end
-
-        footer_files.sort.each do |path|
-          target = path.sub("word/", "")
-          rel = package.document_rels.relationships.find do |r|
-            r.target == target &&
-              r.type.to_s.include?("officeDocument/2006/relationships/footer")
-          end
-          next unless rel
-
-          package.document.header_footer_parts << {
-            r_id: rel.id,
-            target: target,
-            rel_type: rel.type,
-            content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml",
-            content: Uniword::Wordprocessingml::Footer.from_xml(zip_content[path]),
-          }
-        end
-      end
-
-      # Extract image files from word/media/ directory in DOCX
-      #
-      # @param zip_content [Hash] Extracted ZIP content (may have corrupted binary)
-      # @param package [Package] Package to populate
-      # @param zip_path [String, nil] Original ZIP path for binary re-extraction
-      def self.extract_image_parts(zip_content, package, zip_path = nil)
-        return unless package.document
-
-        media_files = zip_content.keys.grep(%r{^word/media/.+$})
-        return if media_files.empty?
-
-        package.document.image_parts ||= {}
-
-        media_files.each do |media_path|
-          filename = File.basename(media_path)
-          ext = File.extname(filename).delete(".").downcase
-          content_type = case ext
-                         when "jpg", "jpeg" then "image/jpeg"
-                         when "png" then "image/png"
-                         when "gif" then "image/gif"
-                         when "bmp" then "image/bmp"
-                         when "tiff", "tif" then "image/tiff"
-                         when "svg" then "image/svg+xml"
-                         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
-
-          binary_data = if zip_path
-                          read_binary_from_zip(zip_path, media_path)
-                        else
-                          zip_content[media_path]
-                        end
-
-          package.document.image_parts[r_id] = {
-            data: binary_data,
-            target: "media/#{filename}",
-            content_type: content_type
-          }
-        end
-      end
-
-      # Read binary data directly from ZIP file without UTF-8 encoding
-      def self.read_binary_from_zip(zip_path, entry_path)
-        require "zip"
-        Zip::File.open(zip_path) do |zip_file|
-          entry = zip_file.find_entry(entry_path)
-          return nil unless entry
-
-          entry.get_input_stream.read
-        end
-      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 +192,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,33 +201,46 @@ module Uniword
         @allocator = IdAllocator.populate_from_package(self)
       end
 
-      # Extract media files from word/theme/media/ directory
-      def self.extract_theme_media(zip_content)
-        media = {}
-
-        zip_content.each_key do |file_path|
-          next unless file_path =~ %r{^word/theme/media/(.+)$}
-
-          filename = Regexp.last_match(1)
-          media[filename] = Uniword::Themes::MediaFile.new(
-            filename: filename,
-            content: zip_content[file_path],
-            source_path: file_path
-          )
-        end
-
-        media
+      # 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
 
       # 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 +251,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
 
@@ -519,27 +316,38 @@ module Uniword
         document&.styles_configuration
       end
 
-      # Find the main document path from package relationships
-      def self.find_main_document_path(package_rels)
-        return nil unless package_rels&.relationships
+      private
 
-        rel = package_rels.relationships.find do |r|
-          r.type.to_s.include?("officeDocument/2006/relationships/officeDocument")
-        end
-        return nil unless rel&.target
+      # 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
 
-        path = rel.target.dup
-        path.sub!(%r{^/}, "")
-        path
+        @applied_fixes.each do |fix|
+          Uniword.logger&.info { "Reconciler fix #{fix}" }
+        end
       end
 
-      # Find the document relationships path from the main document path
-      def self.find_document_rels_path(doc_path)
-        return nil unless doc_path
-
-        dir = File.dirname(doc_path)
-        basename = File.basename(doc_path)
-        File.join(dir, "_rels", "#{basename}.rels")
+      # 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