uniword 1.3.0 → 1.4.1

data/lib/uniword/docx/part_collection.rb

@@ -80,6 +80,10 @@ module Uniword
         @parts.key?(key)
       end
 
+      # Hash-style alias for key? (RSpec's have_key matcher, legacy
+      # callers).
+      alias has_key? key?
+
       # @return [Part, nil] the removed part
       def delete(key)
         @parts.delete(key)
@@ -97,6 +101,14 @@ module Uniword
         value.each { |key, part| self[key] = part }
       end
 
+      # Key attribute => assigner lambda filling the attribute from
+      # the collection key when the part does not carry it.
+      KEY_ASSIGNERS = {
+        r_id: ->(part, key) { part.r_id ||= key },
+        target: ->(part, key) { part.target ||= key },
+        path: ->(part, key) { part.path ||= key },
+      }.freeze
+
       private
 
       def wrap(key, value)
@@ -104,19 +116,15 @@ module Uniword
         when Part
           value
         when Hash
-          @part_class.new(
-            target: value[:target], content: value[:content] || value[:xml],
-          ).tap { |part| assign_key(part, key) }
+          @part_class.from_hash(value).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
+        assigner = KEY_ASSIGNERS[@key_attribute]
+        assigner&.call(part, key.to_s)
       end
     end
   end

data/lib/uniword/docx/part_loader/chart_loader.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class PartLoader
+      # Loads chart parts (word/charts/chartN.xml) into the document's
+      # chart_parts collection, keyed by the id of the document
+      # relationship targeting each chart. Charts without a matching
+      # document relationship are skipped.
+      class ChartLoader
+        # @param context [LoadContext] shared load state
+        # @param definition [Ooxml::PartDefinition] :chart
+        # @return [void]
+        def load(context, definition)
+          package = context.package
+          return unless package.document_rels
+
+          paths = context.matching_paths(definition)
+          return if paths.empty?
+
+          paths.each do |path|
+            load_chart(context, definition, path)
+          end
+        end
+
+        private
+
+        def load_chart(context, definition, path)
+          target = path.delete_prefix("word/")
+          rel = find_chart_relationship(context.package, definition, target)
+          return unless rel
+
+          context.package.document.chart_parts[rel.id] = ChartPart.new(
+            r_id: rel.id,
+            target: target,
+            content: context.zip_content[path],
+          )
+        end
+
+        # The document relationship of the definition's type targeting
+        # the chart, or nil when none targets it.
+        def find_chart_relationship(package, definition, target)
+          package.document_rels.relationships.find do |r|
+            r.target == target && r.type.to_s.include?(definition.rel_type)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/docx/part_loader/custom_xml_loader.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class PartLoader
+      # Loads customXml data items (customXml/itemN.xml) together with
+      # their itemProps and relationships sidecars into
+      # CustomXmlItem objects on the package.
+      class CustomXmlLoader
+        # @param context [LoadContext] shared load state
+        # @param definition [Ooxml::PartDefinition] :custom_xml_item
+        # @return [void]
+        def load(context, definition)
+          item_paths = context.matching_paths(definition)
+          return if item_paths.empty?
+
+          items = item_paths.sort_by { |path| item_index(path) }.map do |path|
+            build_item(context, path)
+          end
+          context.package.custom_xml_items = items
+        end
+
+        private
+
+        def build_item(context, item_path)
+          index = item_index(item_path)
+          CustomXmlItem.new(
+            index: index,
+            xml_content: context.zip_content[item_path],
+            props_xml: context.zip_content[props_path(index)],
+            rels_xml: context.zip_content[sidecar_rels_path(item_path)],
+          )
+        end
+
+        def item_index(path)
+          path[/item(\d+)/, 1].to_i
+        end
+
+        def props_path(index)
+          Ooxml::PartRegistry.find_by_key(:custom_xml_item_props)
+            .path_for(index: index)
+        end
+
+        # OPC relationships sidecar of the item part
+        # ("customXml/item1.xml" → "customXml/_rels/item1.xml.rels").
+        def sidecar_rels_path(item_path)
+          File.join(File.dirname(item_path), "_rels",
+                    "#{File.basename(item_path)}.rels")
+        end
+      end
+    end
+  end
+end

data/lib/uniword/docx/part_loader/embedding_loader.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class PartLoader
+      # Loads OLE/embedded object binaries (word/embeddings/*) into
+      # the package's embeddings collection, keyed by relationship
+      # target (path relative to word/).
+      class EmbeddingLoader
+        # @param context [LoadContext] shared load state
+        # @param definition [Ooxml::PartDefinition] :ole_object
+        # @return [void]
+        def load(context, definition)
+          paths = context.matching_paths(definition)
+          return if paths.empty?
+
+          embeddings = context.package.embeddings
+          paths.each do |path|
+            embeddings[path.delete_prefix("word/")] =
+              context.zip_content[path]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/docx/part_loader/header_footer_loader.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class PartLoader
+      # Loads header and footer parts (word/headerN.xml,
+      # word/footerN.xml) into HeaderFooterPart objects on the
+      # document's unified header/footer store. Registered under the
+      # :header_footer loader key for both the :header and :footer
+      # definitions; the definition selects kind, path pattern,
+      # relationship type, and content model.
+      #
+      # Each part keeps its loaded relationship id, target, and
+      # rel_type verbatim, plus the sectPr reference type
+      # ("default"/"first"/"even") collected from every section
+      # properties element, so the save path can leave loaded
+      # relationships untouched.
+      class HeaderFooterLoader
+        # @param context [LoadContext] shared load state
+        # @param definition [Ooxml::PartDefinition] :header or :footer
+        # @return [void]
+        def load(context, definition)
+          package = context.package
+          return unless package.document && package.document_rels
+
+          paths = context.matching_paths(definition)
+          return if paths.empty?
+
+          load_parts(context, definition, package, paths.sort)
+        end
+
+        private
+
+        # Parse each path and append its part to the document's
+        # header/footer store.
+        def load_parts(context, definition, package, paths)
+          ref_types = reference_types(package.document)
+          store = package.document.header_footer_parts
+          paths.each do |path|
+            part = build_part(context, definition, path, ref_types)
+            store << part if part
+          end
+        end
+
+        # Build the part for one path, or nil when no document
+        # relationship of the definition's type targets it.
+        def build_part(context, definition, path, ref_types)
+          target = path.delete_prefix("word/")
+          rel = find_relationship(context.package, definition, target)
+          return nil unless rel
+
+          HeaderFooterPart.new(
+            kind: definition.key,
+            r_id: rel.id,
+            target: target,
+            rel_type: rel.type,
+            type: ref_types[rel.id],
+            content: definition.loader_model.from_xml(
+              context.zip_content[path],
+            ),
+            loaded: true,
+          )
+        end
+
+        def find_relationship(package, definition, target)
+          package.document_rels.relationships.find do |r|
+            r.target == target && r.type.to_s.include?(definition.rel_type)
+          end
+        end
+
+        # Map relationship id => sectPr reference type
+        # ("default"/"first"/"even") from every section properties
+        # element (body-level and paragraph-level).
+        def reference_types(document)
+          types = {}
+          section_properties_of(document).each do |sect_pr|
+            collect_reference_types(types, sect_pr.header_references)
+            collect_reference_types(types, sect_pr.footer_references)
+          end
+          types
+        end
+
+        def collect_reference_types(types, references)
+          (references || []).each do |ref|
+            types[ref.r_id] = ref.type if ref.r_id
+          end
+        end
+
+        def section_properties_of(document)
+          body = document.body
+          return [] unless body
+
+          from_paragraphs = (body.paragraphs || []).filter_map do |para|
+            para.properties&.section_properties
+          end
+          [body.section_properties, *from_paragraphs].compact
+        end
+      end
+    end
+  end
+end

data/lib/uniword/docx/part_loader/image_loader.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class PartLoader
+      # Loads image parts (word/media/*) into the document's
+      # image_parts collection, keyed by the relationship id the loaded
+      # document rels assign to each media 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.
+      #
+      # The content type is derived from the file extension; the
+      # extension mapping is wider than the registry's Default entries
+      # (bmp, tiff, svg) and preserved verbatim from the historic
+      # load path.
+      class ImageLoader
+        # Extension → content type mapping (wider than the registry's
+        # Default entries; preserved verbatim from the historic load
+        # path).
+        CONTENT_TYPES = {
+          "jpg" => "image/jpeg", "jpeg" => "image/jpeg",
+          "png" => "image/png", "gif" => "image/gif",
+          "bmp" => "image/bmp",
+          "tiff" => "image/tiff", "tif" => "image/tiff",
+          "svg" => "image/svg+xml"
+        }.freeze
+
+        # @param context [LoadContext] shared load state
+        # @param definition [Ooxml::PartDefinition] :image
+        # @return [void]
+        def load(context, definition)
+          package = context.package
+          return unless package.document
+
+          paths = context.matching_paths(definition)
+          return if paths.empty?
+
+          paths.each do |path|
+            load_image(context, definition, path)
+          end
+        end
+
+        private
+
+        def load_image(context, definition, path)
+          package = context.package
+          filename = File.basename(path)
+          r_id = loaded_image_rid(package, definition, filename) ||
+            next_synthetic_image_key(package)
+
+          package.document.image_parts[r_id] = ImagePart.new(
+            r_id: r_id,
+            data: binary_data(context, path),
+            target: "media/#{filename}",
+            content_type: content_type_for(filename),
+          )
+        end
+
+        # The rId a loaded document relationship assigns to
+        # "media/<filename>", or nil when no image rel targets it.
+        def loaded_image_rid(package, definition, filename)
+          rel = package.document_rels&.relationships&.find do |r|
+            r.target == "media/#{filename}" &&
+              r.type.to_s == definition.rel_type
+          end
+          rel&.id
+        end
+
+        # Synthetic image-part key that cannot collide with a loaded
+        # relationship id or an already-keyed image part.
+        def 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
+
+        # Re-read bytes from the original ZIP when available (the
+        # extracted hash may carry corrupted UTF-8 binary).
+        def binary_data(context, path)
+          return context.zip_content[path] unless context.zip_path
+
+          read_binary_from_zip(context.zip_path, path)
+        end
+
+        def 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
+
+        def content_type_for(filename)
+          ext = File.extname(filename).delete(".").downcase
+          CONTENT_TYPES.fetch(ext, "image/#{ext}")
+        end
+      end
+    end
+  end
+end

data/lib/uniword/docx/part_loader/load_context.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class PartLoader
+      # Shared state for one package load: the extracted ZIP entries,
+      # the package being populated, and the main-document paths
+      # resolved from the package-level relationships.
+      class LoadContext
+        # @return [Hash] extracted ZIP entries (package path => content)
+        attr_reader :zip_content
+
+        # @return [Package] package being populated
+        attr_reader :package
+
+        # @return [String, nil] original ZIP path for binary
+        #   re-extraction
+        attr_reader :zip_path
+
+        # @param zip_content [Hash] extracted ZIP entries
+        # @param package [Package] package being populated
+        # @param zip_path [String, nil] original ZIP path
+        def initialize(zip_content:, package:, zip_path: nil)
+          @zip_content = zip_content
+          @package = package
+          @zip_path = zip_path
+        end
+
+        # Zip entry paths matching the definition's fixed path or
+        # path pattern (numbered part families).
+        #
+        # @param definition [Ooxml::PartDefinition]
+        # @return [Array<String>] in zip_content order
+        def matching_paths(definition)
+          zip_content.keys.select { |path| definition.match_path?(path) }
+        end
+
+        # Main document part path, resolved from the package-level
+        # officeDocument relationship.
+        #
+        # @return [String, nil] e.g. "word/document.xml"
+        def main_document_path
+          return @main_document_path if defined?(@main_document_path)
+
+          @main_document_path = find_main_document_path
+        end
+
+        # Relationships part path of the main document, derived from
+        # its resolved path.
+        #
+        # @return [String, nil] e.g. "word/_rels/document.xml.rels"
+        def main_document_rels_path
+          return @main_document_rels_path if defined?(@main_document_rels_path)
+
+          @main_document_rels_path = sidecar_rels_path(main_document_path)
+        end
+
+        private
+
+        def find_main_document_path
+          relationships = package.package_rels&.relationships
+          return nil unless relationships
+
+          office_document = Ooxml::PartRegistry.find_by_key(:document).rel_type
+          rel = relationships.find do |r|
+            r.type.to_s.include?(office_document)
+          end
+          return nil unless rel&.target
+
+          rel.target.dup.delete_prefix("/")
+        end
+
+        # OPC relationships sidecar: sibling "_rels" directory named
+        # after the part ("word/document.xml" →
+        # "word/_rels/document.xml.rels").
+        def sidecar_rels_path(part_path)
+          return nil unless part_path
+
+          File.join(File.dirname(part_path), "_rels",
+                    "#{File.basename(part_path)}.rels")
+        end
+      end
+    end
+  end
+end

data/lib/uniword/docx/part_loader/raw_part_loader.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class PartLoader
+      # Fallback loader: preserves ZIP entries no registry definition
+      # claims as raw parts (RawPart) on the package, so unmodelled
+      # parts (docProps/meta.xml, glossary documents, VBA projects,
+      # unmodelled .rels sidecars, ...) round-trip byte-for-byte with
+      # their content types and relationships intact.
+      #
+      # Runs last (load_priority 130 on the :raw_parts definition), so
+      # the registry claims every path it models first and this loader
+      # carries only the remainder — no double emission. A path is
+      # claimed when any PartDefinition matches it (loadable or not),
+      # when it is the resolved main document part (or its rels
+      # sidecar) at a non-standard location, or when it is a customXml
+      # item rels sidecar consumed by CustomXmlLoader.
+      #
+      # Bytes are re-read from the original ZIP when available (the
+      # extracted hash may carry corrupted UTF-8 binary); content
+      # types come from the loaded [Content_Types].xml model.
+      class RawPartLoader
+        # customXml item rels sidecars are consumed by CustomXmlLoader
+        # together with their item part (captured group: item index).
+        CUSTOM_XML_ITEM_RELS =
+          %r{\AcustomXml/_rels/item(\d+)\.xml\.rels\z}
+
+        # @param context [LoadContext] shared load state
+        # @param _definition [Ooxml::PartDefinition] :raw_parts
+        #   (strategy interface; the loader claims by remainder, not
+        #   by definition matching)
+        # @return [void]
+        def load(context, _definition)
+          paths = unclaimed_paths(context)
+          return if paths.empty?
+
+          bytes = raw_bytes(context, paths)
+          paths.each do |path|
+            next unless bytes[path]
+
+            context.package.raw_parts[path] = build_part(
+              context.package, path, bytes[path]
+            )
+          end
+        end
+
+        private
+
+        # @return [Array<String>] ZIP entries claimed by no registry
+        #   loader, in zip_content order
+        def unclaimed_paths(context)
+          context.zip_content.keys.reject { |path| claimed?(context, path) }
+        end
+
+        def claimed?(context, path)
+          return true if Ooxml::PartRegistry.find_by_path(path)
+          return true if path == context.main_document_path
+          return true if path == context.main_document_rels_path
+
+          custom_xml_item_rels?(context, path)
+        end
+
+        # A customXml item rels sidecar is claimed (via CustomXmlItem)
+        # when its item part is present in the ZIP.
+        def custom_xml_item_rels?(context, path)
+          match = CUSTOM_XML_ITEM_RELS.match(path)
+          return false unless match
+
+          context.zip_content.key?("customXml/item#{match[1]}.xml")
+        end
+
+        # @return [RawPart]
+        def build_part(package, path, content)
+          rel = referencing_relationship(package, path)
+          RawPart.new(
+            path: path,
+            content: content,
+            content_type: content_type_for(package, path),
+            r_id: rel&.id,
+            rel_type: rel&.type,
+          )
+        end
+
+        # Bytes for each path: re-read from the original ZIP when
+        # available (binary-safe), else the extracted content.
+        #
+        # @return [Hash] package path => bytes
+        def raw_bytes(context, paths)
+          unless context.zip_path
+            return paths.to_h { |p| [p, context.zip_content[p]] }
+          end
+
+          read_from_zip(context.zip_path, paths)
+        end
+
+        def read_from_zip(zip_path, paths)
+          require "zip"
+          Zip::File.open(zip_path) do |zip_file|
+            paths.to_h do |path|
+              entry = zip_file.find_entry(path)
+              [path, entry&.get_input_stream&.read]
+            end
+          end
+        end
+
+        # Content type the source [Content_Types].xml declared for the
+        # part: its Override first, else the Default for its extension.
+        #
+        # @return [String, nil] nil when the source declared neither
+        def content_type_for(package, path)
+          content_types = package.content_types
+          return nil unless content_types
+
+          override_type(content_types, path) ||
+            default_type(content_types, path)
+        end
+
+        def override_type(content_types, path)
+          part_name = "/#{path}"
+          content_types.overrides.find do |o|
+            o.part_name == part_name
+          end&.content_type
+        end
+
+        def default_type(content_types, path)
+          ext = File.extname(path)[1..]
+          return nil unless ext
+
+          content_types.defaults.find do |d|
+            d.extension == ext
+          end&.content_type
+        end
+
+        # The first relationship in a modelled rels part whose
+        # resolved target is this part, or nil. Recorded as metadata
+        # only; the rel itself stays in its rels collection.
+        def referencing_relationship(package, path)
+          rels_collections(package).each do |rels, base_dir|
+            rel = rels&.relationships&.find do |r|
+              resolve_target(base_dir, r.target.to_s) == path
+            end
+            return rel if rel
+          end
+          nil
+        end
+
+        # [rels collection, base directory] pairs mirroring the rels
+        # parts the package models.
+        def rels_collections(package)
+          [
+            [package.package_rels, ""],
+            [package.document_rels, "word"],
+            [package.settings_rels, "word"],
+            [package.theme_rels, "word/theme"],
+            [package.footnotes_rels, "word"],
+            [package.endnotes_rels, "word"],
+          ]
+        end
+
+        # Resolve a relationship target to a normalized package path,
+        # handling package-absolute (leading slash) targets and "..".
+        def resolve_target(base_dir, target)
+          return target[1..] if target.start_with?("/")
+
+          normalize_package_path(File.join(base_dir, target))
+        end
+
+        # Lexically normalize a package-relative path (resolve "." and
+        # ".." segments).
+        def normalize_package_path(path)
+          segments = []
+          path.split("/").each do |segment|
+            next if segment.empty? || segment == "."
+
+            segment == ".." ? segments.pop : segments << segment
+          end
+          segments.join("/")
+        end
+      end
+    end
+  end
+end

data/lib/uniword/docx/part_loader/theme_media_loader.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class PartLoader
+      # Loads theme media files (word/theme/media/*) into the parsed
+      # theme's media_files. Runs only when a theme part was loaded —
+      # theme media without a theme is ignored, as before.
+      class ThemeMediaLoader
+        # @param context [LoadContext] shared load state
+        # @param definition [Ooxml::PartDefinition] :theme_media
+        # @return [void]
+        def load(context, definition)
+          theme = context.package.theme
+          return unless theme
+
+          media = extract_media(context, definition)
+          theme.media_files = media if media.any?
+        end
+
+        private
+
+        # @return [Hash] filename => Themes::MediaFile
+        def extract_media(context, definition)
+          prefix = definition.pattern_prefix
+          paths = context.matching_paths(definition)
+          paths.each_with_object({}) do |path, media|
+            filename = path.delete_prefix(prefix)
+            media[filename] = Uniword::Themes::MediaFile.new(
+              filename: filename,
+              content: context.zip_content[path],
+              source_path: path,
+            )
+          end
+        end
+      end
+    end
+  end
+end