uniword 1.0.0

data/lib/uniword/metadata/metadata_validator.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+# All classes autoloaded via lib/uniword/metadata.rb and lib/uniword/configuration.rb
+
+module Uniword
+  module Metadata
+    # Validates metadata against schema.
+    #
+    # Responsibility: Validate metadata against schema rules.
+    # Single Responsibility: Only handles metadata validation.
+    #
+    # The MetadataValidator:
+    # - Validates field types (string, integer, array, etc.)
+    # - Validates field constraints (required, max_length, etc.)
+    # - Validates field values (allowed_values, pattern, etc.)
+    # - Validates dependencies between fields
+    # - Returns detailed validation errors
+    #
+    # Does NOT handle: Extraction, updating, or indexing.
+    # Those responsibilities belong to separate classes.
+    #
+    # @example Validate metadata
+    #   validator = MetadataValidator.new
+    #   result = validator.validate(metadata)
+    #   puts "Valid: #{result[:valid]}"
+    #   puts "Errors: #{result[:errors]}"
+    #
+    # @example Validate for specific scenario
+    #   result = validator.validate(metadata, scenario: :publication)
+    class MetadataValidator
+      # @return [Hash] Loaded schema configuration
+      attr_reader :schema
+
+      # Initialize a new MetadataValidator.
+      #
+      # @param config_file [String] Path to schema configuration
+      #
+      # @example Create validator
+      #   validator = MetadataValidator.new
+      #
+      # @example Custom schema
+      #   validator = MetadataValidator.new(
+      #     config_file: 'config/custom_schema.yml'
+      #   )
+      def initialize(config_file: 'metadata_schema')
+        @schema = load_schema(config_file)
+      end
+
+      # Validate metadata against schema.
+      #
+      # @param metadata [Metadata, Hash] Metadata to validate
+      # @param scenario [Symbol, nil] Validation scenario (:publication, :archival)
+      # @return [Hash] Validation result with :valid and :errors keys
+      #
+      # @example Validate metadata
+      #   result = validator.validate(metadata)
+      #   if result[:valid]
+      #     puts "Valid!"
+      #   else
+      #     puts "Errors: #{result[:errors].join(', ')}"
+      #   end
+      def validate(metadata, scenario: nil)
+        meta = metadata.is_a?(Metadata) ? metadata : Metadata.new(metadata)
+        errors = []
+
+        # Validate field types and constraints
+        validate_core_properties(meta, errors)
+        validate_extended_properties(meta, errors)
+        validate_statistical_metadata(meta, errors)
+        validate_content_metadata(meta, errors)
+
+        # Validate scenario-specific requirements
+        validate_scenario_requirements(meta, scenario, errors) if scenario
+
+        # Validate field dependencies
+        validate_dependencies(meta, errors)
+
+        {
+          valid: errors.empty?,
+          errors: errors
+        }
+      end
+
+      # Check if metadata is valid.
+      #
+      # @param metadata [Metadata, Hash] Metadata to validate
+      # @param scenario [Symbol, nil] Validation scenario
+      # @return [Boolean] true if valid
+      #
+      # @example Check validity
+      #   valid = validator.valid?(metadata)
+      def valid?(metadata, scenario: nil)
+        validate(metadata, scenario: scenario)[:valid]
+      end
+
+      # Get validation errors for metadata.
+      #
+      # @param metadata [Metadata, Hash] Metadata to validate
+      # @param scenario [Symbol, nil] Validation scenario
+      # @return [Array<String>] Validation errors
+      #
+      # @example Get errors
+      #   errors = validator.errors(metadata)
+      def errors(metadata, scenario: nil)
+        validate(metadata, scenario: scenario)[:errors]
+      end
+
+      private
+
+      # Load schema from configuration file.
+      #
+      # @param config_file [String] Configuration file name or path
+      # @return [Hash] Loaded schema
+      def load_schema(config_file)
+        if File.exist?(config_file)
+          Configuration::ConfigurationLoader.load_file(config_file)
+        else
+          Configuration::ConfigurationLoader.load(config_file)
+        end
+      rescue Configuration::ConfigurationError => e
+        warn "Warning: #{e.message}. Using default schema."
+        default_schema
+      end
+
+      # Get default schema.
+      #
+      # @return [Hash] Default schema
+      def default_schema
+        {
+          core_properties: {},
+          extended_properties: {},
+          statistical_metadata: {},
+          content_metadata: {}
+        }
+      end
+
+      # Validate core properties.
+      #
+      # @param metadata [Metadata] Metadata to validate
+      # @param errors [Array] Errors array to populate
+      def validate_core_properties(metadata, errors)
+        return unless @schema[:core_properties]
+
+        @schema[:core_properties].each do |key, rules|
+          validate_field(metadata, key, rules, errors)
+        end
+      end
+
+      # Validate extended properties.
+      #
+      # @param metadata [Metadata] Metadata to validate
+      # @param errors [Array] Errors array to populate
+      def validate_extended_properties(metadata, errors)
+        return unless @schema[:extended_properties]
+
+        @schema[:extended_properties].each do |key, rules|
+          validate_field(metadata, key, rules, errors)
+        end
+      end
+
+      # Validate statistical metadata.
+      #
+      # @param metadata [Metadata] Metadata to validate
+      # @param errors [Array] Errors array to populate
+      def validate_statistical_metadata(metadata, errors)
+        return unless @schema[:statistical_metadata]
+
+        @schema[:statistical_metadata].each do |key, rules|
+          validate_field(metadata, key, rules, errors)
+        end
+      end
+
+      # Validate content metadata.
+      #
+      # @param metadata [Metadata] Metadata to validate
+      # @param errors [Array] Errors array to populate
+      def validate_content_metadata(metadata, errors)
+        return unless @schema[:content_metadata]
+
+        @schema[:content_metadata].each do |key, rules|
+          validate_field(metadata, key, rules, errors)
+        end
+      end
+
+      # Validate a single field.
+      #
+      # @param metadata [Metadata] Metadata to validate
+      # @param key [Symbol] Field key
+      # @param rules [Hash] Validation rules
+      # @param errors [Array] Errors array to populate
+      def validate_field(metadata, key, rules, errors)
+        value = metadata[key]
+
+        # Check required
+        if rules[:required] && value.nil?
+          errors << "#{key} is required"
+          return
+        end
+
+        # Skip further validation if value is nil and not required
+        return if value.nil?
+
+        # Validate type
+        validate_type(key, value, rules[:type], errors)
+
+        # Validate constraints
+        validate_constraints(key, value, rules, errors)
+      end
+
+      # Validate field type.
+      #
+      # @param key [Symbol] Field key
+      # @param value [Object] Field value
+      # @param expected_type [String] Expected type
+      # @param errors [Array] Errors array to populate
+      def validate_type(key, value, expected_type, errors)
+        return unless expected_type
+
+        valid = case expected_type.to_s
+                when 'string'
+                  value.is_a?(String)
+                when 'integer'
+                  value.is_a?(Integer)
+                when 'float'
+                  value.is_a?(Float) || value.is_a?(Integer)
+                when 'boolean'
+                  value.is_a?(TrueClass) || value.is_a?(FalseClass)
+                when 'array'
+                  value.is_a?(Array)
+                when 'hash'
+                  value.is_a?(Hash)
+                when 'datetime'
+                  value.is_a?(Time) || value.is_a?(DateTime) || value.is_a?(Date)
+                else
+                  true
+                end
+
+        return if valid
+
+        errors << "#{key} must be of type #{expected_type}, got #{value.class}"
+      end
+
+      # Validate field constraints.
+      #
+      # @param key [Symbol] Field key
+      # @param value [Object] Field value
+      # @param rules [Hash] Validation rules
+      # @param errors [Array] Errors array to populate
+      def validate_constraints(key, value, rules, errors)
+        # Max length for strings
+        if rules[:max_length] && value.is_a?(String) && (value.length > rules[:max_length])
+          errors << "#{key} exceeds maximum length of #{rules[:max_length]}"
+        end
+
+        # Min/max value for numbers
+        if rules[:min_value] && value.is_a?(Numeric) && (value < rules[:min_value])
+          errors << "#{key} must be at least #{rules[:min_value]}"
+        end
+
+        if rules[:max_value] && value.is_a?(Numeric) && (value > rules[:max_value])
+          errors << "#{key} cannot exceed #{rules[:max_value]}"
+        end
+
+        # Max items for arrays
+        if rules[:max_items] && value.is_a?(Array) && (value.size > rules[:max_items])
+          errors << "#{key} exceeds maximum of #{rules[:max_items]} items"
+        end
+
+        # Allowed values
+        if rules[:allowed_values] && !rules[:allowed_values].include?(value)
+          errors << "#{key} must be one of: #{rules[:allowed_values].join(', ')}"
+        end
+
+        # Pattern matching for strings
+        return unless rules[:pattern] && value.is_a?(String)
+        return if value.match?(Regexp.new(rules[:pattern]))
+
+        errors << "#{key} does not match required pattern"
+      end
+
+      # Validate scenario-specific requirements.
+      #
+      # @param metadata [Metadata] Metadata to validate
+      # @param scenario [Symbol] Validation scenario
+      # @param errors [Array] Errors array to populate
+      def validate_scenario_requirements(metadata, scenario, errors)
+        return unless @schema[:validation_rules]
+
+        scenario_key = :"required_for_#{scenario}"
+        required_fields = @schema[:validation_rules][scenario_key]
+        return unless required_fields
+
+        required_fields.each do |field|
+          field_key = field.to_sym
+          errors << "#{field_key} is required for #{scenario}" if metadata[field_key].nil?
+        end
+      end
+
+      # Validate field dependencies.
+      #
+      # @param metadata [Metadata] Metadata to validate
+      # @param errors [Array] Errors array to populate
+      def validate_dependencies(metadata, errors)
+        return unless @schema[:validation_rules]
+        return unless @schema[:validation_rules][:dependencies]
+
+        @schema[:validation_rules][:dependencies].each do |field, conditions|
+          field_value = metadata[field]
+          next unless field_value
+
+          conditions.each do |value, requirements|
+            next unless field_value.to_s == value.to_s
+
+            required_fields = requirements[:requires] || []
+            required_fields.each do |req_field|
+              req_key = req_field.to_sym
+              if metadata[req_key].nil?
+                errors << "#{req_field} is required when #{field} is '#{value}'"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/metadata.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Metadata
+    autoload :Metadata, "#{__dir__}/metadata/metadata"
+    autoload :MetadataExtractor, "#{__dir__}/metadata/metadata_extractor"
+    autoload :MetadataIndex, "#{__dir__}/metadata/metadata_index"
+    autoload :MetadataManager, "#{__dir__}/metadata/metadata_manager"
+    autoload :MetadataUpdater, "#{__dir__}/metadata/metadata_updater"
+    autoload :MetadataValidator, "#{__dir__}/metadata/metadata_validator"
+  end
+end

data/lib/uniword/mhtml/css_number_formatter.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Mhtml
+    # Formats CSS numeric values for Word-compatible MHTML.
+    #
+    # Responsibility: Provide consistent CSS number formatting with proper
+    # units, precision, and handling of edge cases like zero values.
+    #
+    # @example Format a font size
+    #   CssNumberFormatter.format(16, 'pt')  # => "16pt"
+    #
+    # @example Format a margin with precision
+    #   CssNumberFormatter.format(1.5, 'pt')  # => "1.5pt"
+    #
+    # @example Format zero value
+    #   CssNumberFormatter.format(0, 'px')  # => "0"
+    class CssNumberFormatter
+      # Default decimal precision for CSS values
+      DEFAULT_PRECISION = 2
+
+      # Units that should be omitted for zero values
+      OMIT_UNIT_FOR_ZERO = %w[px pt em rem % cm mm in].freeze
+
+      # Convert twips to points (1pt = 20 twips)
+      TWIPS_PER_POINT = 20
+
+      # Format a CSS number value with appropriate unit and precision.
+      #
+      # @param value [Numeric, nil] The numeric value
+      # @param unit [String] The CSS unit (pt, px, em, %, in, cm, mm)
+      # @param precision [Integer] Decimal places (default: 2)
+      # @return [String, nil] Formatted CSS value or nil if value is nil
+      #
+      # @example Format with default precision
+      #   format(12.5, 'pt')  # => "12.5pt"
+      #
+      # @example Format zero value
+      #   format(0, 'px')  # => "0"
+      #
+      # @example Format with custom precision
+      #   format(1.23456, 'em', 3)  # => "1.235em"
+      def self.format(value, unit, precision: DEFAULT_PRECISION)
+        return nil if value.nil?
+
+        # Convert to float
+        numeric_value = value.to_f
+
+        # Handle zero specially - omit unit
+        return '0' if numeric_value.zero? && OMIT_UNIT_FOR_ZERO.include?(unit)
+
+        # Round to specified precision
+        rounded = numeric_value.round(precision)
+
+        # Format and remove unnecessary trailing zeros
+        formatted = if rounded == rounded.to_i
+                      rounded.to_i.to_s
+                    else
+                      # Format with precision, then remove trailing zeros
+                      Kernel.format("%.#{precision}f", rounded).sub(/\.?0+$/, '')
+                    end
+
+        "#{formatted}#{unit}"
+      end
+
+      # Convert twips to points and format.
+      #
+      # @param twips [Numeric, nil] Value in twips
+      # @param precision [Integer] Decimal places (default: 2)
+      # @return [String, nil] Formatted value in points
+      #
+      # @example Convert 1440 twips to inches
+      #   twips_to_pt(1440)  # => "72pt"
+      def self.twips_to_pt(twips, precision: DEFAULT_PRECISION)
+        return nil if twips.nil?
+
+        points = twips.to_f / TWIPS_PER_POINT
+        format(points, 'pt', precision: precision)
+      end
+
+      # Convert twips to inches and format.
+      #
+      # @param twips [Numeric, nil] Value in twips
+      # @param precision [Integer] Decimal places (default: 2)
+      # @return [String, nil] Formatted value in inches
+      #
+      # @example Convert 1440 twips to inches
+      #   twips_to_in(1440)  # => "1in"
+      def self.twips_to_in(twips, precision: DEFAULT_PRECISION)
+        return nil if twips.nil?
+
+        # 1 inch = 1440 twips
+        inches = twips.to_f / 1440.0
+        format(inches, 'in', precision: precision)
+      end
+
+      # Format a font size value (typically in half-points).
+      #
+      # @param half_points [Numeric, nil] Font size in half-points
+      # @param precision [Integer] Decimal places (default: 1)
+      # @return [String, nil] Formatted font size
+      #
+      # @example Format font size
+      #   format_font_size(24)  # => "12pt"
+      def self.format_font_size(half_points, precision: 1)
+        return nil if half_points.nil?
+
+        points = half_points.to_f / 2.0
+        format(points, 'pt', precision: precision)
+      end
+
+      # Format percentage value.
+      #
+      # @param value [Numeric, nil] Percentage value (0-100)
+      # @param precision [Integer] Decimal places (default: 0)
+      # @return [String, nil] Formatted percentage
+      #
+      # @example Format percentage
+      #   format_percentage(50)  # => "50%"
+      def self.format_percentage(value, precision: 0)
+        return nil if value.nil?
+
+        format(value, '%', precision: precision)
+      end
+    end
+  end
+end

data/lib/uniword/mhtml/document.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Uniword
+  module Mhtml
+    # MHTML Document — top-level model for .mht/.mhtml/.doc files.
+    #
+    # This is COMPLETELY SEPARATE from OOXML Wordprocessingml::DocumentRoot.
+    # MHTML uses MIME multipart format with HTML content, not ZIP + OOXML XML.
+    #
+    # Structure:
+    #   Mhtml::Document
+    #     ├── html_part (HtmlPart) — main document HTML
+    #     ├── parts[] (MimePart) — all MIME parts (images, XML, theme, etc.)
+    #     ├── document_properties (Metadata::DocumentProperties)
+    #     ├── word_document_settings (Metadata::WordDocumentSettings)
+    #     └── filelist_xml (String)
+    class Document < Lutaml::Model::Serializable
+      # MIME headers
+      attribute :mime_version, :string, default: -> { '1.0' }
+      attribute :boundary, :string
+
+      # Main HTML part (first/largest text/html part)
+      attribute :html_part, HtmlPart
+
+      # All MIME parts (including the HTML part)
+      attribute :parts, :array, default: -> { [] }
+
+      # Parsed metadata from HTML head XML blocks
+      attribute :document_properties, Metadata::DocumentProperties
+      attribute :office_document_settings, Metadata::OfficeDocumentSettings
+      attribute :word_document_settings, Metadata::WordDocumentSettings
+      attribute :latent_styles_raw, :string
+
+      # Convenience accessors
+
+      # @return [HtmlPart] The main HTML part
+      def html
+        @html_part
+      end
+
+      # Raw HTML string of the main HTML part
+      def raw_html
+        html_part&.decoded_content
+      end
+
+      def raw_html=(value)
+        self.html_part ||= HtmlPart.new
+        html_part.content_type = 'text/html'
+        html_part.content_transfer_encoding = 'quoted-printable'
+        html_part.raw_content = value
+      end
+
+      # Body inner HTML
+      def body_html
+        html_part&.body_html
+      end
+
+      # CSS styles from HTML head
+      def css_styles
+        html_part&.css_styles
+      end
+
+      # Text content (stripped of HTML tags)
+      def text
+        return '' unless raw_html
+
+        raw_html
+          .gsub(/<[^>]+>/, ' ')
+          .gsub('&lt;', '<')
+          .gsub('&gt;', '>')
+          .gsub('&amp;', '&')
+          .gsub('&quot;', '"')
+          .gsub('&#39;', "'")
+          .gsub('&nbsp;', ' ')
+          .gsub(/\s+/, ' ')
+          .strip
+      end
+
+      # File parts by type
+
+      # @return [Array<XmlPart>] All XML parts
+      def xml_parts
+        parts.grep(XmlPart)
+      end
+
+      # @return [Array<ImagePart>] All image parts
+      def image_parts
+        parts.grep(ImagePart)
+      end
+
+      # @return [ThemePart, nil] Theme data part
+      def theme_part
+        parts.find { |p| p.is_a?(ThemePart) }
+      end
+
+      # @return [XmlPart, nil] Filelist XML part
+      def filelist_part
+        parts.find { |p| p.is_a?(XmlPart) && p.filename == 'filelist.xml' }
+      end
+
+      # @return [String, nil] Filelist XML content
+      def filelist_xml
+        filelist_part&.decoded_content
+      end
+
+      # @return [XmlPart, nil] Color scheme mapping part
+      def color_scheme_mapping_part
+        parts.find do |p|
+          p.is_a?(XmlPart) && p.filename&.include?('colorschememapping')
+        end
+      end
+
+      # @return [String, nil] Color scheme mapping XML
+      def color_scheme_mapping_xml
+        color_scheme_mapping_part&.decoded_content
+      end
+
+      # @return [Array<HeaderFooterPart>] Header/footer HTML parts
+      def header_footer_parts
+        parts.grep(HeaderFooterPart)
+      end
+
+      # @return [String, nil] Header HTML
+      def header_html
+        header_footer_parts.find { |p| p.filename&.include?('header') }&.decoded_content
+      end
+
+      # @return [String, nil] Footer HTML (placeholder)
+      def footer_html
+        header_footer_parts.find { |p| p.filename&.include?('footer') }&.decoded_content
+      end
+
+      # @return [String, nil] Placeholder header HTML
+      def placeholder_html
+        header_footer_parts.find { |p| p.filename&.include?('plchdr') }&.decoded_content
+      end
+
+      # @return [Hash] Images as filename => decoded data
+      def images
+        image_parts.each_with_object({}) do |part, hash|
+          hash[part.filename] = part.decoded_content if part.filename
+        end
+      end
+
+      # Add a MIME part
+      def add_part(part)
+        parts << part
+        self
+      end
+
+      # Build a summary of the document structure
+      def inspect
+        "#<#{self.class} parts=#{parts.length} images=#{image_parts.length} " \
+          "xml=#{xml_parts.length} theme=#{theme_part ? 'yes' : 'no'}>"
+      end
+    end
+  end
+end

data/lib/uniword/mhtml/header_footer_part.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Mhtml
+    # Header/Footer HTML MIME part — separate HTML files for headers/footers.
+    class HeaderFooterPart < MimePart
+      def html_content
+        decoded_content
+      end
+    end
+  end
+end