uniword 1.0.0

data/lib/uniword/image.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'securerandom'
+
+module Uniword
+  # Represents an image (inline element)
+  # Responsibility: Hold image reference and metadata
+  #
+  # An image is an inline element that references an external image file.
+  # It contains metadata about the image such as dimensions and relationship ID.
+  #
+  # Uses lazy loading to defer loading of actual image data until needed,
+  # which improves memory efficiency for documents with many images.
+  class Image < Element
+    extend LazyLoader
+
+    # OOXML namespace configuration for images (drawing elements)
+    xml do
+      element 'drawing'
+      namespace Ooxml::Namespaces::WordProcessingML
+    end
+
+    # Image relationship ID (reference to the image file in the package)
+    attribute :relationship_id, :string
+
+    # Image width (in EMUs - English Metric Units)
+    attribute :width, :integer
+
+    # Image height (in EMUs - English Metric Units)
+    attribute :height, :integer
+
+    # Alternative text for accessibility
+    attribute :alt_text, :string
+
+    # Image title/description
+    attribute :title, :string
+
+    # Image filename/path (for reference)
+    attribute :filename, :string
+
+    # Positioning attributes
+    # Whether image is inline with text (default: true)
+    attribute :inline, :boolean, default: -> { true }
+
+    # Horizontal alignment (:left, :center, :right)
+    attribute :horizontal_alignment, :string
+
+    # Vertical alignment (:top, :middle, :bottom)
+    attribute :vertical_alignment, :string
+
+    # Text wrapping style (:square, :tight, :through, :none, etc.)
+    attribute :text_wrapping, :string
+
+    # Image data loader (proc that loads the actual binary data)
+    # This is not serialized - it's used for lazy loading
+    attr_accessor :data_loader
+
+    # Cached image data (lazy loaded)
+    attr_reader :cached_data
+
+    # Load image data lazily
+    #
+    # @return [String, nil] The binary image data
+    def image_data
+      return @image_data if defined?(@image_data)
+
+      @image_data = @data_loader&.call
+    end
+
+    # Check if image data is loaded
+    #
+    # @return [Boolean] true if image data is cached
+    def image_data_loaded?
+      defined?(@cached_data)
+    end
+
+    # Clear cached image data to free memory
+    #
+    # @return [void]
+    def clear_image_data
+      remove_instance_variable(:@cached_data) if defined?(@cached_data)
+    end
+
+    # Set image data (for manual assignment)
+    #
+    # @param data [String] The binary image data
+    # @return [String] The data
+    def image_data=(data)
+      @cached_data = data
+    end
+
+    # Get image size without loading full data
+    #
+    # @return [Integer, nil] The size in bytes if data is loaded
+    def image_size
+      return nil unless image_data_loaded?
+
+      @cached_data&.bytesize
+    end
+
+    # Set floating mode (not inline)
+    #
+    # @return [Boolean] true
+    def floating=(value)
+      self.inline = !value
+    end
+
+    # Check if image is floating (not inline)
+    #
+    # @return [Boolean] true if floating
+    def floating
+      !inline
+    end
+
+    # Accept a visitor for the visitor pattern
+    #
+    # @param visitor [Object] The visitor object
+    # @return [Object] The result of the visit operation
+    def accept(visitor)
+      visitor.visit_image(self)
+    end
+
+    # Get text content (images have no text)
+    # Compatible with Run API for text extraction
+    #
+    # @return [String] Empty string (images don't have text)
+    def text
+      ''
+    end
+
+    # Get properties (images don't have RunProperties)
+    # Compatible with Run API for serialization
+    #
+    # @return [nil] Always returns nil (images don't have RunProperties)
+    def properties
+      nil
+    end
+
+    # Get width in points (converted from EMUs)
+    # 1 point = 12700 EMUs
+    #
+    # @return [Float, nil] Width in points
+    def width_in_points
+      return nil unless width
+
+      width / 12_700.0
+    end
+
+    # Get height in points (converted from EMUs)
+    # 1 point = 12700 EMUs
+    #
+    # @return [Float, nil] Height in points
+    def height_in_points
+      return nil unless height
+
+      height / 12_700.0
+    end
+
+    # Get width in pixels (assuming 96 DPI)
+    # 1 pixel = 9525 EMUs at 96 DPI
+    #
+    # @return [Integer, nil] Width in pixels
+    def width_in_pixels
+      return nil unless width
+
+      (width / 9525.0).round
+    end
+
+    # Get height in pixels (assuming 96 DPI)
+    # 1 pixel = 9525 EMUs at 96 DPI
+    #
+    # @return [Integer, nil] Height in pixels
+    def height_in_pixels
+      return nil unless height
+
+      (height / 9525.0).round
+    end
+
+    # Get aspect ratio
+    #
+    # @return [Float, nil] Aspect ratio (width/height)
+    def aspect_ratio
+      return nil unless width && height&.positive?
+
+      width.to_f / height
+    end
+
+    # Create image from base64 encoded data
+    #
+    # @param base64_data [String] Base64 encoded image data
+    # @param width [Integer, nil] Width in EMUs
+    # @param height [Integer, nil] Height in EMUs
+    # @param alt_text [String, nil] Alternative text
+    # @param title [String, nil] Image title
+    # @return [Image] New image instance
+    def self.from_base64(base64_data, width: nil, height: nil, alt_text: nil, title: nil)
+      binary_data = Base64.decode64(base64_data)
+      from_data(binary_data, width: width, height: height, alt_text: alt_text, title: title)
+    end
+
+    # Create image from binary data
+    #
+    # @param binary_data [String] Binary image data
+    # @param width [Integer, nil] Width in EMUs
+    # @param height [Integer, nil] Height in EMUs
+    # @param alt_text [String, nil] Alternative text
+    # @param title [String, nil] Image title
+    # @return [Image] New image instance
+    def self.from_data(binary_data, width: nil, height: nil, alt_text: nil, title: nil)
+      image = new(
+        width: width,
+        height: height,
+        alt_text: alt_text,
+        title: title,
+        relationship_id: "temp_#{SecureRandom.hex(8)}"
+      )
+      image.image_data = binary_data
+      image
+    end
+
+    # Save image data to a file
+    # Convenient method to save image data to disk
+    #
+    # @param path [String] The file path to save to
+    # @return [Integer] Number of bytes written
+    # @raise [RuntimeError] if no image data is available
+    def save(path)
+      data_to_save = image_data
+      raise 'No image data available to save' unless data_to_save
+
+      File.binwrite(path, data_to_save)
+    end
+
+    protected
+
+    # Validate that required attributes are present
+    #
+    # @return [Boolean] true if relationship_id is present
+    def required_attributes_valid?
+      !relationship_id.nil? && !relationship_id.empty?
+    end
+  end
+end

data/lib/uniword/infrastructure/mime_packager.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'base64'
+
+module Uniword
+  module Infrastructure
+    # Serializes Mhtml::Document to MHTML MIME format.
+    #
+    # Rebuilds the MIME multipart structure from the document model,
+    # encoding content appropriately (QP for text, base64 for binary).
+    #
+    # @example Serialize to file
+    #   packager = MimePackager.from_document(document)
+    #   packager.package("output.doc")
+    class MimePackager
+      attr_reader :document, :boundary
+
+      # Create packager from an Mhtml::Document.
+      #
+      # @param document [Mhtml::Document] The document to serialize
+      def initialize(document)
+        @document = document
+        @boundary = document.boundary || generate_boundary
+      end
+
+      # Create packager from document (class method for compatibility).
+      def self.from_document(document)
+        new(document)
+      end
+
+      # Package document to MHTML file.
+      #
+      # @param output_path [String] The output file path
+      def package(output_path)
+        raise ArgumentError, 'Output path cannot be nil' if output_path.nil?
+        raise ArgumentError, 'Output path cannot be empty' if output_path.empty?
+
+        File.write(output_path, build_mime_content, encoding: 'UTF-8')
+      end
+
+      # Build complete MIME content as string.
+      #
+      # @return [String] The complete MHTML content
+      def build_mime_content
+        parts = []
+
+        # MIME global header
+        parts << 'MIME-Version: 1.0'
+        parts << "Content-Type: multipart/related; boundary=\"#{boundary}\""
+        parts << ''
+
+        # HTML part (main document)
+        parts << build_part(document.html_part) if document.html_part
+
+        # All other parts (XML, images, theme, etc.)
+        document.parts.each do |part|
+          next if part == document.html_part
+
+          parts << build_part(part)
+        end
+
+        # Final boundary
+        parts << "--#{boundary}--"
+        parts << ''
+
+        parts.join("\r\n")
+      end
+
+      private
+
+      # Build a single MIME part.
+      def build_part(part)
+        lines = []
+
+        # Boundary
+        lines << "--#{boundary}"
+
+        # Headers
+        lines << "Content-Location: #{part.content_location}" if part.content_location
+        if part.content_transfer_encoding
+          lines << "Content-Transfer-Encoding: #{part.content_transfer_encoding}"
+        end
+
+        if part.content_type
+          ct = part.content_type
+          # Add charset for text types
+          ct += '; charset="utf-8"' if ct.start_with?('text/') && !ct.include?('charset')
+          lines << "Content-Type: #{ct}"
+        end
+
+        lines << "Content-ID: <#{part.content_id}>" if part.content_id
+
+        # Empty line separating headers from body
+        lines << ''
+
+        # Body — encode if needed
+        encoding = part.content_transfer_encoding
+        if encoding == 'quoted-printable'
+          # Use decoded_content to avoid double-encoding on round-trip
+          body = quoted_printable_encode(part.decoded_content)
+        elsif encoding == 'base64'
+          begin
+            # Decoded content (round-trip: raw_content is already base64)
+            body = Base64.strict_encode64(part.decoded_content)
+          rescue ArgumentError
+            # New part: raw_content is raw binary data
+            body = Base64.strict_encode64(part.raw_content)
+          end
+          body = body.gsub(/.{1,76}/, "\\0\r\n").rstrip
+        else
+          body = part.raw_content
+        end
+        lines << body
+
+        lines.join("\r\n")
+      end
+
+      # Generate unique MIME boundary.
+      def generate_boundary
+        salt = SecureRandom.uuid.tr('-', '.')[0..17]
+        "----=_NextPart_#{salt}"
+      end
+
+      # Quoted-printable encode content
+      # Encodes special characters and uses soft line breaks
+      # RFC 2045: only '=' (61) and control chars (0-31, 127) must be encoded
+      def quoted_printable_encode(content)
+        result = []
+        line_length = 0
+        max_line_length = 76
+
+        content.bytes.each do |byte|
+          char = byte.chr
+          # Encode only '=' and control characters per RFC 2045
+          if byte == 61 || byte < 33 || byte > 126
+            result << ('=%02X' % byte)
+            line_length += 3
+          else
+            result << char
+            line_length += 1
+          end
+
+          # Soft line break if line gets too long
+          if line_length >= max_line_length - 1
+            result << "=\r\n"
+            line_length = 0
+          end
+        end
+
+        result.join
+      end
+    end
+  end
+end

data/lib/uniword/infrastructure/mime_parser.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Uniword
+  module Infrastructure
+    # Parses MHTML (MIME HTML) files into Mhtml::Document model.
+    #
+    # Parses MIME multipart structure, decodes content transfer encodings,
+    # creates typed MimePart objects, and populates Mhtml::Document.
+    #
+    # @example Parse an MHTML file
+    #   parser = Uniword::Infrastructure::MimeParser.new
+    #   document = parser.parse("document.mhtml")
+    class MimeParser
+      # Parse MHTML file and return a populated Mhtml::Document.
+      #
+      # @param path [String] The file path to parse
+      # @return [Mhtml::Document] The parsed document
+      # @raise [ArgumentError] if path is nil or file not found
+      def parse(path)
+        raise ArgumentError, 'Path cannot be nil' if path.nil?
+        raise ArgumentError, "File not found: #{path}" unless File.exist?(path)
+
+        content = File.read(path, encoding: 'UTF-8')
+        parse_content(content)
+      end
+
+      # Parse MHTML content string.
+      #
+      # @param content [String] The MHTML content to parse
+      # @return [Mhtml::Document] The parsed document
+      def parse_content(content)
+        @content = content
+        @boundary = extract_boundary
+        @raw_parts = split_parts
+
+        document = Mhtml::Document.new
+        document.boundary = @boundary
+
+        @raw_parts.each do |part|
+          mime_part = parse_mime_part(part)
+          next unless mime_part
+
+          document.html_part = mime_part if mime_part.is_a?(Mhtml::HtmlPart) && !document.html_part
+
+          document.add_part(mime_part)
+        end
+
+        extract_metadata(document)
+        document
+      end
+
+      private
+
+      # Extract MIME boundary from content.
+      def extract_boundary
+        if (match = @content.match(/boundary="([^"]+)"/))
+          match[1]
+        elsif (match = @content.match(/boundary=([^\s;]+)/))
+          match[1]
+        else
+          raise 'No MIME boundary found in content'
+        end
+      end
+
+      # Split content into raw MIME part strings.
+      def split_parts
+        parts = @content.split(/--#{Regexp.escape(@boundary)}/)
+        parts.reject! { |p| p.strip.empty? || p.strip == '--' }
+        # Skip the global MIME header (Content-Type: multipart/related)
+        # Strip leading CRLF first since boundary lines end with \r\n
+        parts.reject! { |p| p.gsub(/^\r?\n/, '').match?(/^Content-Type:\s*multipart/i) }
+        parts
+      end
+
+      # Parse a single raw MIME part into a typed MimePart.
+      def parse_mime_part(raw_part)
+        headers, body = raw_part.split(/\r?\n\r?\n/, 2)
+        return nil unless body
+
+        # Strip leading CRLF from headers (boundary lines end with \r\n)
+        headers = headers.gsub(/^\r?\n/, '')
+
+        content_type = extract_header(headers, 'Content-Type')
+        content_location = extract_header(headers, 'Content-Location')
+        encoding = extract_header(headers, 'Content-Transfer-Encoding')
+        content_id = extract_header(headers, 'Content-ID')
+
+        mime_part = create_typed_part(content_type)
+        return nil unless mime_part
+
+        mime_part.content_type = content_type
+        mime_part.content_location = content_location
+        mime_part.content_transfer_encoding = encoding
+        mime_part.content_id = content_id&.gsub(/[<>]/, '')
+        mime_part.raw_content = body.rstrip
+
+        mime_part
+      end
+
+      # Create a typed MimePart based on content type.
+      def create_typed_part(content_type)
+        return nil unless content_type
+
+        case content_type
+        when %r{text/html}i
+          Mhtml::HtmlPart.new
+        when %r{image/}i
+          Mhtml::ImagePart.new
+        when %r{application/vnd.ms-officetheme}i
+          Mhtml::ThemePart.new
+        when %r{text/xml|application/xml}i
+          Mhtml::XmlPart.new
+        else
+          Mhtml::MimePart.new
+        end
+      end
+
+      # Extract header value from headers string.
+      def extract_header(headers, header_name)
+        if (match = headers.match(/^#{header_name}:\s*(.+?)$/i))
+          match[1].strip
+        end
+      end
+
+      # Extract metadata from HTML part into document model.
+      def extract_metadata(document)
+        html = document.html_part
+        return unless html
+
+        # Parse DocumentProperties
+        props_xml = html.document_properties_xml
+        if props_xml
+          begin
+            document.document_properties =
+              Mhtml::Metadata::DocumentProperties.from_xml(props_xml)
+          rescue StandardError
+            # Store raw if parsing fails
+            document.document_properties =
+              Mhtml::Metadata::DocumentProperties.new
+          end
+        end
+
+        # Parse OfficeDocumentSettings
+        ods_xml = html.office_document_settings_xml
+        if ods_xml
+          begin
+            document.office_document_settings =
+              Mhtml::Metadata::OfficeDocumentSettings.from_xml(ods_xml)
+          rescue StandardError
+            document.office_document_settings =
+              Mhtml::Metadata::OfficeDocumentSettings.new
+          end
+        end
+
+        # Parse WordDocument settings
+        wd_xml = html.word_document_xml
+        if wd_xml
+          begin
+            document.word_document_settings =
+              Mhtml::Metadata::WordDocumentSettings.from_xml(wd_xml)
+          rescue StandardError
+            document.word_document_settings =
+              Mhtml::Metadata::WordDocumentSettings.new
+          end
+        end
+
+        # Store LatentStyles as raw XML (too many entries to model individually)
+        ls_xml = html.latent_styles_xml
+        document.latent_styles_raw = ls_xml if ls_xml
+
+        # Classify header/footer HTML parts
+        document.parts.each do |part|
+          next unless part.is_a?(Mhtml::HtmlPart)
+          next if part == document.html_part
+
+          fname = part.filename
+          next unless fname&.include?('header') || fname&.include?('footer') ||
+                      fname&.include?('plchdr')
+
+          # Convert to HeaderFooterPart
+          idx = document.parts.index(part)
+          hf = Mhtml::HeaderFooterPart.new
+          hf.content_type = part.content_type
+          hf.content_location = part.content_location
+          hf.content_transfer_encoding = part.content_transfer_encoding
+          hf.content_id = part.content_id
+          hf.raw_content = part.raw_content
+          document.parts[idx] = hf
+        end
+      end
+    end
+  end
+end

data/lib/uniword/infrastructure/xml_namespace_normalizer.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module Uniword
+  module Infrastructure
+    # XML normalization utilities for round-trip fidelity
+    #
+    # Ensures that serialized XML matches the expected namespace declaration format
+    # by adding missing prefixed namespace declarations to root elements.
+    module XmlNamespaceNormalizer
+      # Prefixed namespaces that should be declared at root level in OOXML documents
+      PREFIXED_NAMESPACES = {
+        'http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing' => 'wp',
+        'http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing' => 'wp14'
+      }.freeze
+
+      # Normalize XML to ensure prefixed namespace declarations are at root level
+      #
+      # @param xml [String] XML content
+      # @return [String] Normalized XML content
+      def self.normalize(xml)
+        doc = Nokogiri::XML(xml)
+        return xml unless doc.root
+
+        # Check if any prefixed namespaces are used but not declared at root
+        root = doc.root
+        root_ns = root.namespace_definitions.to_h { |ns| [ns.prefix, ns.href] }
+
+        PREFIXED_NAMESPACES.each do |uri, expected_prefix|
+          # Check if this namespace URI is used in the document
+          elements_with_ns = doc.xpath("//*[namespace-uri()='#{uri}']")
+          next if elements_with_ns.empty?
+
+          # Check if the expected prefix is already declared at root
+          if root_ns.key?(expected_prefix) && (root_ns[expected_prefix] == uri)
+            # Check if the URI matches
+            next
+          end
+
+          # Check if default namespace with this URI exists
+          default_ns = root_ns.find { |k, v| k.nil? && v == uri }
+
+          if default_ns
+            # Replace default namespace with prefixed namespace
+            # Find the default xmlns attribute and rename it
+            root.attributes.each do |name, attr|
+              next unless name == 'xmlns' && attr.value == uri
+
+              # Remove the default namespace
+              root.remove_attribute('xmlns')
+              # Add the prefixed namespace
+              root["xmlns:#{expected_prefix}"] = uri
+
+              # Update all elements that use this namespace to use the prefix
+              update_elements_namespace(elements_with_ns, expected_prefix)
+              break
+            end
+          else
+            # Namespace is used but not declared at root - add it
+            root["xmlns:#{expected_prefix}"] = uri
+          end
+        end
+
+        doc.to_xml(indent: 0, save_with: Nokogiri::XML::Node::SaveOptions::AS_XML)
+      end
+
+      # Update elements to use the correct namespace prefix
+      #
+      # @param elements [Nokogiri::XML::NodeSet] Elements to update
+      # @param prefix [String] The prefix to use
+      def self.update_elements_namespace(elements, prefix)
+        elements.each do |el|
+          # Update the element's namespace
+          ns = el.document.root.namespaces.find do |_k, v|
+            v == el.namespace.href
+          end
+          next unless ns
+
+          # Change namespace key from default to prefixed
+          el.document.root.namespaces.delete(ns[0])
+          el.document.root["xmlns:#{prefix}"] = ns[1]
+        end
+      end
+
+      # Normalize namespace declarations in a ZIP content hash
+      #
+      # @param zip_content [Hash] File path => content mapping
+      # @param target_files [Array<String>] Files to normalize
+      # @return [Hash] Updated zip content
+      def self.normalize_zip_content(zip_content, target_files = nil)
+        result = zip_content.dup
+        target_files ||= result.keys.select { |k| k.end_with?('.xml') || k.end_with?('.rels') }
+
+        target_files.each do |path|
+          next unless result[path]
+
+          result[path] = normalize(result[path])
+        end
+
+        result
+      end
+    end
+  end
+end