uniword 1.2.5 → 1.3.0

data/lib/uniword/spreadsheetml/shared_string_table.rb

@@ -11,8 +11,8 @@ module Uniword
     class SharedStringTable < Lutaml::Model::Serializable
       attribute :count, :integer
       attribute :unique_count, :integer
-      attribute :si_entries, :stringItem, collection: true,
-                                          initialize_empty: true
+      attribute :si_entries, StringItem, collection: true,
+                                         initialize_empty: true
 
       xml do
         element "sst"

data/lib/uniword/spreadsheetml/table_formula.rb

@@ -14,8 +14,8 @@ module Uniword
       xml do
         element "tableFormula"
         namespace Uniword::Ooxml::Namespaces::SpreadsheetML
-        mixed_content
 
+        map_content to: :content
         map_attribute "array", to: :array, render_nil: false
       end
     end

data/lib/uniword/template/variable_resolver.rb

@@ -101,22 +101,55 @@ module Uniword
 
       # Navigate to a property on an object
       #
+      # Dispatches on the object's class: Hash keys, declared attributes
+      # of Lutaml::Model objects, or public zero-arity readers on plain
+      # Ruby objects.
+      #
       # @param object [Object] Object to navigate
       # @param property [String] Property name
       # @return [Object] Property value or nil
       def navigate_property(object, property)
-        # For hashes, use key access
-        if object.is_a?(Hash)
+        case object
+        when Hash
           object[property.to_sym] || object[property]
+        when Lutaml::Model::Serializable
+          read_model_attribute(object, property)
         else
-          # public_send is the canonical Ruby idiom for template-driven
-          # property access on arbitrary user objects. The property name
-          # comes from template syntax and may reference any public
-          # reader method on the model.
-          object.public_send(property.to_sym)
+          read_object_property(object, property)
         end
       end
 
+      # Read a declared attribute from a Lutaml::Model object
+      #
+      # Only attributes declared in the model's schema are readable from
+      # templates; arbitrary public methods are not exposed. The schema
+      # acts as the allowlist, the model's public method table provides
+      # the value.
+      #
+      # @param object [Lutaml::Model::Serializable] Model instance
+      # @param property [String] Property name
+      # @return [Object] Attribute value or nil when not declared
+      def read_model_attribute(object, property)
+        name = property.to_sym
+        return unless object.class.attributes.key?(name)
+
+        object.method(name).call
+      end
+
+      # Read a property from a plain Ruby object
+      #
+      # Looks the property up in the object's public method table.
+      # Returns nil when the object has no such public method.
+      #
+      # @param object [Object] Object to read from
+      # @param property [String] Property name
+      # @return [Object] Property value or nil
+      def read_object_property(object, property)
+        object.method(property.to_sym).call
+      rescue NameError
+        nil
+      end
+
       # Parse literal value from string
       #
       # @param value [String] Literal value string

data/lib/uniword/themes/theme_transformation.rb

@@ -52,34 +52,10 @@ module Uniword
         )
       end
 
-      private
-
-      OFFICE_THEME_PATH = File.expand_path(
-        "../../../data/themes/office_theme.xml", __dir__
-      ).freeze
-
-      def default_format_scheme
-        @default_format_scheme ||= begin
-          theme = Drawingml::Theme.from_xml(File.read(OFFICE_THEME_PATH))
-          theme.theme_elements.fmt_scheme
-        end
-      end
-
-      # Build OOXML ThemeElements from friendly theme
+      # Build OOXML ColorScheme from friendly color scheme.
       #
-      # @param friendly [Themes::Theme] Friendly theme
-      # @return [Drawingml::ThemeElements] OOXML theme elements
-      def build_theme_elements(friendly)
-        return nil unless friendly
-
-        Drawingml::ThemeElements.new(
-          clr_scheme: build_color_scheme(friendly.color_scheme),
-          font_scheme: build_font_scheme(friendly.font_scheme),
-          fmt_scheme: default_format_scheme,
-        )
-      end
-
-      # Build OOXML ColorScheme from friendly color scheme
+      # Public converter, used by partial theme edits (Design → Colors
+      # style scheme swaps that keep fonts and formats untouched).
       #
       # @param friendly_colors [Themes::ColorScheme, nil] Friendly color scheme
       # @return [Drawingml::ColorScheme, nil] OOXML color scheme
@@ -103,6 +79,58 @@ module Uniword
         )
       end
 
+      # Build OOXML FontScheme from friendly font scheme.
+      #
+      # Public converter, used by partial theme edits (Design → Fonts
+      # style scheme swaps that keep colors and formats untouched).
+      #
+      # @param friendly_fonts [Themes::FontScheme, nil] Friendly font scheme
+      # @return [Drawingml::FontScheme, nil] OOXML font scheme
+      def build_font_scheme(friendly_fonts)
+        return nil unless friendly_fonts
+
+        Drawingml::FontScheme.new(
+          name: friendly_fonts.name,
+          major_font_obj: build_major_font(friendly_fonts),
+          minor_font_obj: build_minor_font(friendly_fonts),
+        )
+      end
+
+      # A fresh parse of the bundled default Office theme.
+      #
+      # Each call re-parses the bundled XML so every returned theme (and
+      # its elements) is independent — callers may mutate it freely.
+      #
+      # @return [Drawingml::Theme] Default Office theme
+      def default_office_theme
+        Drawingml::Theme.from_xml(File.read(OFFICE_THEME_PATH))
+      end
+
+      private
+
+      OFFICE_THEME_PATH = File.expand_path(
+        "../../../data/themes/office_theme.xml", __dir__
+      ).freeze
+
+      def default_format_scheme
+        @default_format_scheme ||=
+          default_office_theme.theme_elements.fmt_scheme
+      end
+
+      # Build OOXML ThemeElements from friendly theme
+      #
+      # @param friendly [Themes::Theme] Friendly theme
+      # @return [Drawingml::ThemeElements] OOXML theme elements
+      def build_theme_elements(friendly)
+        return nil unless friendly
+
+        Drawingml::ThemeElements.new(
+          clr_scheme: build_color_scheme(friendly.color_scheme),
+          font_scheme: build_font_scheme(friendly.font_scheme),
+          fmt_scheme: default_format_scheme,
+        )
+      end
+
       # Build OOXML color reference from hex value
       #
       # Creates the appropriate color type (Dk1Color, Lt1Color, etc.)
@@ -118,20 +146,6 @@ module Uniword
         color_class.new.tap { |c| c.rgb = hex }
       end
 
-      # Build OOXML FontScheme from friendly font scheme
-      #
-      # @param friendly_fonts [Themes::FontScheme, nil] Friendly font scheme
-      # @return [Drawingml::FontScheme, nil] OOXML font scheme
-      def build_font_scheme(friendly_fonts)
-        return nil unless friendly_fonts
-
-        Drawingml::FontScheme.new(
-          name: friendly_fonts.name,
-          major_font_obj: build_major_font(friendly_fonts),
-          minor_font_obj: build_minor_font(friendly_fonts),
-        )
-      end
-
       # Build OOXML MajorFont from friendly font scheme
       #
       # @param friendly [Themes::FontScheme] Friendly font scheme

data/lib/uniword/toc/toc_generator.rb

@@ -91,6 +91,8 @@ module Uniword
         # Add the SDT to element_order so it serializes correctly
         return unless body.element_order
 
+        # element_order from the parser may be frozen; never mutate it.
+        body.element_order = body.element_order.dup
         insert_element = Lutaml::Xml::Element.new("Element", "sdt")
         if position.positive? && body.element_order.size >= position
           body.element_order.insert(position, insert_element)

data/lib/uniword/validation/engine.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Validation
+    # The single validation engine.
+    #
+    # Runs the rules registered in Rules::Registry against a validation
+    # context and returns Report::ValidationIssue results. One engine, two
+    # front-ends:
+    #
+    # - On-disk (post-save): Rules::DocumentContext wraps the DOCX package;
+    #   driven by Validators::DocumentSemanticsValidator (verify layer 3).
+    # - In-memory (pre-save): Rules::ModelContext wraps the document model;
+    #   driven by Wordprocessingml::DocumentRoot#valid? and CLI `validate`.
+    #
+    # Rules declare which context they consume via Rules::Base#context_type
+    # (:package or :model); only matching rules run.
+    module Engine
+      # Run every rule matching the context's type.
+      #
+      # @param context [Rules::DocumentContext, Rules::ModelContext]
+      #   validation context; its #context_type selects the rule set
+      # @param rules [Array<Rules::Base>] candidate rules
+      # @return [Array<Report::ValidationIssue>] issues found
+      def self.run(context, rules: Rules::Registry.all)
+        rules.each_with_object([]) do |rule, issues|
+          next unless rule.context_type == context.context_type
+          next unless rule.applicable?(context)
+
+          issues.concat(rule.check(context))
+        end
+      end
+    end
+  end
+end

data/lib/uniword/validation/link_checker.rb

@@ -19,7 +19,7 @@ module Uniword
     # @example Create a custom checker
     #   class MyChecker < LinkChecker
     #     def can_check?(link)
-    #       link.respond_to?(:custom_field)
+    #       link.is_a?(Uniword::Wordprocessingml::Hyperlink)
     #     end
     #
     #     def check(link, document)

data/lib/uniword/validation/opc_validator.rb

@@ -2,7 +2,6 @@
 
 require "zip"
 require "nokogiri"
-require_relative "report/validation_issue"
 
 module Uniword
   module Validation

data/lib/uniword/validation/report/layer_result.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "lutaml/model"
-require_relative "validation_issue"
 
 module Uniword
   module Validation

data/lib/uniword/validation/report/terminal_formatter.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "rainbow"
-require_relative "verification_report"
 
 module Uniword
   module Validation

data/lib/uniword/validation/report/verification_report.rb

@@ -2,8 +2,6 @@
 
 require "lutaml/model"
 require "time"
-require_relative "validation_issue"
-require_relative "layer_result"
 
 module Uniword
   module Validation

data/lib/uniword/validation/report.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Validation
+    # Reporting value objects for validation and verification results.
+    #
+    # Registered here via autoload so any namespace can reference the
+    # report classes without load-order coupling.
+    module Report
+      autoload :ValidationIssue,
+               "uniword/validation/report/validation_issue"
+      autoload :LayerResult,
+               "uniword/validation/report/layer_result"
+      autoload :VerificationReport,
+               "uniword/validation/report/verification_report"
+      autoload :TerminalFormatter,
+               "uniword/validation/report/terminal_formatter"
+    end
+  end
+end

data/lib/uniword/validation/rules/base.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../report/validation_issue"
-
 module Uniword
   module Validation
     module Rules
@@ -64,6 +62,16 @@ module Uniword
           "error"
         end
 
+        # The context type this rule consumes. The Engine runs a rule
+        # only when the context's type matches: :package rules validate
+        # an on-disk DOCX via DocumentContext; :model rules validate an
+        # in-memory document model via ModelContext (see ModelRule).
+        #
+        # @return [Symbol] :package or :model
+        def context_type
+          :package
+        end
+
         # Check if this rule applies to the given document context.
         #
         # @param context [DocumentContext] The document being validated

data/lib/uniword/validation/rules/bookmark_pairing_rule.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Validation
+    module Rules
+      # DOC-201: every bookmarkStart must have a matching bookmarkEnd.
+      #
+      # Unpaired bookmark starts produce corrupt documents that Word
+      # refuses to open.
+      class BookmarkPairingRule < ModelRule
+        def code = "DOC-201"
+        def category = :bookmarks
+        def severity = "error"
+
+        def check(context)
+          body = context.document.body
+          return [] unless body
+
+          end_ids = (body.bookmark_ends || []).filter_map(&:id).to_set
+          (body.bookmark_starts || []).filter_map do |start|
+            unpaired_issue(start, end_ids)
+          end
+        end
+
+        private
+
+        # @return [Report::ValidationIssue, nil] issue when unpaired
+        def unpaired_issue(start, end_ids)
+          return if end_ids.include?(start.id)
+
+          issue("bookmarkStart id='#{start.id}' (name='#{start.name}') " \
+                "has no matching bookmarkEnd",
+                part: "word/document.xml")
+        end
+      end
+    end
+  end
+end

data/lib/uniword/validation/rules/bookmark_uniqueness_rule.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Validation
+    module Rules
+      # DOC-202: bookmark names should be unique.
+      #
+      # Duplicate names confuse cross-references and GoTo navigation.
+      # The Word-internal "_GoBack" bookmark is exempt.
+      class BookmarkUniquenessRule < ModelRule
+        def code = "DOC-202"
+        def category = :bookmarks
+        def severity = "warning"
+
+        def check(context)
+          body = context.document.body
+          return [] unless body
+
+          duplicates(body.bookmark_starts || []).map do |name|
+            issue("Duplicate bookmark name '#{name}'",
+                  part: "word/document.xml")
+          end
+        end
+
+        private
+
+        # @param starts [Array] bookmarkStart models
+        # @return [Array<String>] names seen more than once
+        def duplicates(starts)
+          seen = {}
+          starts.each_with_object([]) do |start, dups|
+            name = tracked_name(start)
+            next unless name
+
+            dups << name if seen[name]
+            seen[name] = true
+          end
+        end
+
+        # @return [String, nil] name worth tracking, nil when exempt
+        def tracked_name(start)
+          name = start.name.to_s
+          name unless name.empty? || name == "_GoBack"
+        end
+      end
+    end
+  end
+end

data/lib/uniword/validation/rules/bookmarks_rule.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Uniword
   module Validation
     module Rules

data/lib/uniword/validation/rules/content_types_coverage_rule.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Uniword
   module Validation
     module Rules

data/lib/uniword/validation/rules/core_properties_namespace_rule.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Uniword
   module Validation
     module Rules

data/lib/uniword/validation/rules/document_body_rule.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Validation
+    module Rules
+      # DOC-200: the document must have a body.
+      #
+      # A w:document without w:body carries no content; every document
+      # must contain exactly one body element.
+      class DocumentBodyRule < ModelRule
+        def code = "DOC-200"
+        def category = :structure
+        def severity = "error"
+
+        def check(context)
+          return [] if context.document.body
+
+          [issue("Document body is missing",
+                 part: "word/document.xml",
+                 suggestion: "Add a w:body element to the document.")]
+        end
+      end
+    end
+  end
+end

data/lib/uniword/validation/rules/document_context.rb

@@ -32,6 +32,13 @@ module Uniword
           @moxml = Moxml.new(:nokogiri)
         end
 
+        # Context type used by the Engine to select rules.
+        #
+        # @return [Symbol] :package — this context wraps an on-disk DOCX
+        def context_type
+          :package
+        end
+
         # Open the ZIP archive.
         #
         # @return [Zip::File]

data/lib/uniword/validation/rules/empty_paragraphs_rule.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Validation
+    module Rules
+      # DOC-203: paragraphs should not be empty.
+      #
+      # Empty paragraphs are usually leftover scaffolding; reported as
+      # warnings only.
+      class EmptyParagraphsRule < ModelRule
+        def code = "DOC-203"
+        def category = :structure
+        def severity = "warning"
+
+        def check(context)
+          paragraphs = context.document.paragraphs
+          paragraphs.each_with_index.filter_map do |para, idx|
+            next unless para.runs.nil? || para.runs.empty?
+
+            issue("Empty paragraph at index #{idx}",
+                  part: "word/document.xml")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/validation/rules/font_table_signature_rule.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Uniword
   module Validation
     module Rules

data/lib/uniword/validation/rules/fonts_rule.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Uniword
   module Validation
     module Rules

data/lib/uniword/validation/rules/footnotes_rule.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Uniword
   module Validation
     module Rules

data/lib/uniword/validation/rules/headers_footers_rule.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Uniword
   module Validation
     module Rules

data/lib/uniword/validation/rules/images_rule.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Uniword
   module Validation
     module Rules

data/lib/uniword/validation/rules/mc_ignorable_namespace_rule.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Uniword
   module Validation
     module Rules

data/lib/uniword/validation/rules/model_context.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Validation
+    module Rules
+      # In-memory validation context: wraps a document model.
+      #
+      # Counterpart to DocumentContext (which wraps an on-disk DOCX
+      # package). Model-level rules consume this context via the Engine.
+      #
+      # @example Validate a built document
+      #   context = ModelContext.new(document)
+      #   issues = Validation::Engine.run(context)
+      class ModelContext
+        # @return [Wordprocessingml::DocumentRoot] the document model
+        attr_reader :document
+
+        # @param document [Wordprocessingml::DocumentRoot] in-memory model
+        def initialize(document)
+          @document = document
+        end
+
+        # Context type used by the Engine to select rules.
+        #
+        # @return [Symbol] :model — this context wraps an in-memory model
+        def context_type
+          :model
+        end
+      end
+    end
+  end
+end

data/lib/uniword/validation/rules/model_rule.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Validation
+    module Rules
+      # Base class for in-memory (model-level) validation rules.
+      #
+      # Model rules run against a Rules::ModelContext — the pre-save
+      # front-end of the validation engine — and inspect the document
+      # model directly instead of parsing package XML.
+      #
+      # @example Implement a model rule
+      #   class MyModelRule < ModelRule
+      #     def code = "DOC-900"
+      #
+      #     def check(context)
+      #       return [] if context.document.body
+      #
+      #       [issue("Document body is missing")]
+      #     end
+      #   end
+      #
+      #   Rules::Registry.register(MyModelRule)
+      class ModelRule < Base
+        # Model rules consume the in-memory ModelContext.
+        #
+        # @return [Symbol] :model
+        def context_type
+          :model
+        end
+      end
+    end
+  end
+end

data/lib/uniword/validation/rules/numbering_preservation_rule.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Uniword
   module Validation
     module Rules

data/lib/uniword/validation/rules/numbering_rule.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Uniword
   module Validation
     module Rules

data/lib/uniword/validation/rules/relationship_integrity_rule.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "zip"
-require_relative "base"
 
 module Uniword
   module Validation