uniword 1.2.5 → 1.4.0

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

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class PartLoader
+      # Loads fixed-path XML parts: parses the part's XML with the
+      # definition's loader_model and assigns the model to the
+      # definition's package attribute. Covers every part whose load
+      # is "parse one part into one attribute": the content types,
+      # all rels parts, docProps, the main document, styles,
+      # numbering, settings, font table, web settings, theme,
+      # footnotes, endnotes, and comments.
+      #
+      # Definitions with a path_resolution rule resolve their path
+      # dynamically (main document via the package officeDocument
+      # relationship; its rels part as the sidecar of the resolved
+      # path), falling back to the definition's fixed path.
+      class XmlModelLoader
+        # @param context [LoadContext] shared load state
+        # @param definition [Ooxml::PartDefinition] part to load
+        # @return [void]
+        def load(context, definition)
+          content = read_content(context, definition)
+          return unless content
+
+          model = definition.loader_model.from_xml(content)
+          context.package.method(:"#{definition.package_attribute}=")
+            .call(model)
+        end
+
+        private
+
+        # Part content from the first candidate path present in the
+        # ZIP, preserving the historic resolved-then-fixed fallback.
+        def read_content(context, definition)
+          candidate_paths(context, definition).each do |path|
+            content = context.zip_content[path]
+            return content if content
+          end
+          nil
+        end
+
+        def candidate_paths(context, definition)
+          case definition.path_resolution
+          when :office_document
+            [context.main_document_path, definition.path].compact
+          when :office_document_rels
+            [context.main_document_rels_path, definition.path].compact
+          else
+            [definition.path]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/docx/part_loader.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    # Registry-driven loader for DOCX package parts.
+    #
+    # Replaces the former hand-written per-part sequence in
+    # Package.from_zip_content: parts load by iterating
+    # Ooxml::PartRegistry.loadable (ordered by
+    # Ooxml::PartDefinition#load_priority) and dispatching each
+    # definition to the loader strategy registered under
+    # Ooxml::PartDefinition#loader.
+    #
+    # Open/closed: a new part kind adds a strategy class plus a
+    # register_loader call and a PartRegistry registration — this loop
+    # never changes.
+    #
+    # @example Load parts into a package
+    #   package = Package.new
+    #   PartLoader.load(zip_content, package, zip_path: "doc.docx")
+    class PartLoader
+      autoload :LoadContext, "#{__dir__}/part_loader/load_context"
+      autoload :XmlModelLoader, "#{__dir__}/part_loader/xml_model_loader"
+      autoload :CustomXmlLoader,
+               "#{__dir__}/part_loader/custom_xml_loader"
+      autoload :HeaderFooterLoader,
+               "#{__dir__}/part_loader/header_footer_loader"
+      autoload :ChartLoader, "#{__dir__}/part_loader/chart_loader"
+      autoload :ImageLoader, "#{__dir__}/part_loader/image_loader"
+      autoload :EmbeddingLoader,
+               "#{__dir__}/part_loader/embedding_loader"
+      autoload :ThemeMediaLoader,
+               "#{__dir__}/part_loader/theme_media_loader"
+      autoload :RawPartLoader,
+               "#{__dir__}/part_loader/raw_part_loader"
+
+      class << self
+        # Load every registered part from extracted ZIP content into
+        # the package.
+        #
+        # @param zip_content [Hash] extracted ZIP entries
+        #   (package path => content)
+        # @param package [Package] package to populate
+        # @param zip_path [String, nil] original ZIP path for binary
+        #   re-extraction (image bytes)
+        # @return [Package] the populated package
+        def load(zip_content, package, zip_path: nil)
+          context = LoadContext.new(zip_content: zip_content,
+                                    package: package, zip_path: zip_path)
+          Ooxml::PartRegistry.loadable.each do |definition|
+            loader_for(definition.loader).load(context, definition)
+          end
+          package
+        end
+
+        # Register a loader strategy under a key.
+        #
+        # @param key [Symbol] PartDefinition#loader value
+        # @param strategy [#load] strategy responding to
+        #   +load(context, definition)+
+        # @return [Object] the registered strategy
+        def register_loader(key, strategy)
+          loaders[key.to_sym] = strategy
+        end
+
+        # @param key [Symbol] PartDefinition#loader value
+        # @return [#load] the registered strategy
+        # @raise [ArgumentError] when no strategy is registered
+        def loader_for(key)
+          loaders.fetch(key.to_sym) do
+            raise ArgumentError, "unknown part loader: #{key.inspect}"
+          end
+        end
+
+        private
+
+        def loaders
+          @loaders ||= {}
+        end
+      end
+
+      register_loader(:xml_model, XmlModelLoader.new)
+      register_loader(:custom_xml, CustomXmlLoader.new)
+      register_loader(:header_footer, HeaderFooterLoader.new)
+      register_loader(:chart, ChartLoader.new)
+      register_loader(:image, ImageLoader.new)
+      register_loader(:embedding, EmbeddingLoader.new)
+      register_loader(:theme_media, ThemeMediaLoader.new)
+      register_loader(:raw, RawPartLoader.new)
+    end
+  end
+end

data/lib/uniword/docx/raw_part.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    # A package part no Ooxml::PartDefinition models, carried verbatim
+    # for round-trip fidelity (e.g. docProps/meta.xml, glossary
+    # documents, VBA projects, unmodelled .rels sidecars).
+    #
+    # Unlike document-scoped parts (charts, images, embeddings), a raw
+    # part keeps its full package-relative +path+ — raw parts live
+    # anywhere in the package, not only under word/. Content is the
+    # exact source byte stream (binary-safe; never parsed or
+    # re-encoded), plus the content type the source
+    # [Content_Types].xml declared for it (Override first, then
+    # Default by extension; nil when the source declared neither).
+    #
+    # The relationship referencing the part (when one exists in a
+    # modelled .rels part) is recorded as +r_id+/+rel_type+ metadata
+    # for introspection parity with other part kinds; emission never
+    # uses it — relationships re-serialize from the loaded rels
+    # models, so the source rel survives untouched.
+    #
+    # Raw parts are a fallback: PartLoader claims every registry-known
+    # path first and RawPartLoader carries only the remainder, so a
+    # part is never emitted twice.
+    #
+    # @example
+    #   part = RawPart.new(
+    #     path: "docProps/meta.xml",
+    #     content: bytes,
+    #     content_type: "application/xml",
+    #   )
+    #   part.package_paths # => ["docProps/meta.xml"]
+    class RawPart < Part
+      # @return [String, nil] package-relative path, verbatim
+      attr_writer :path
+
+      # @param path [String, nil] package-relative path
+      #   (e.g. "docProps/meta.xml")
+      # @param content [String, nil] raw part bytes (binary-safe)
+      # @param content_type [String, nil] content type declared by the
+      #   source [Content_Types].xml
+      # @param r_id [String, nil] id of the relationship referencing
+      #   this part (metadata only)
+      # @param rel_type [String, nil] type of the relationship
+      #   referencing this part (metadata only)
+      def initialize(path: nil, content: nil, content_type: nil,
+                     r_id: nil, rel_type: nil)
+        super(content: content, content_type: content_type,
+              r_id: r_id, rel_type: rel_type)
+        @path = path
+      end
+
+      # Wrap a raw-hash entry ({ path:, content:, content_type: })
+      # into a RawPart. Used by PartCollection to normalize hash
+      # assignments.
+      #
+      # @param hash [Hash] raw hash entry
+      # @return [RawPart]
+      def self.from_hash(hash)
+        new(path: hash[:path], content: hash[:content],
+            content_type: hash[:content_type],
+            r_id: hash[:r_id], rel_type: hash[:rel_type])
+      end
+
+      # Package-relative path of the emitted part, carried verbatim
+      # (overrides Part's word/-prefixed target derivation).
+      #
+      # @return [String, nil] e.g. "word/glossary/document.xml"
+      def path
+        @path
+      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