uniword 1.5.2 → 1.5.4

data/lib/uniword/diff/semantic/paragraph_comparator.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Diff
+    module Semantic
+      # LCS-based paragraph comparator. Aligns old and new paragraph
+      # lists with a proper dynamic-programming LCS, classifies each
+      # aligned pair, and emits changes for any pair that isn't
+      # :unchanged.
+      #
+      # Reuses the paragraph text via `Paragraph#text`.
+      module ParagraphComparator
+        module_function
+
+        # @param old_paras [Array<Wordprocessingml::Paragraph>]
+        # @param new_paras [Array<Wordprocessingml::Paragraph>]
+        # @yieldparam change [Change]
+        # @return [void]
+        def each_change(old_paras, new_paras, &block)
+          old_paras ||= []
+          new_paras ||= []
+          old_keys = old_paras.map { |p| fingerprint(p) }
+          new_keys = new_paras.map { |p| fingerprint(p) }
+          alignment = align(old_keys, new_keys)
+
+          emit_changes(alignment, old_paras, new_paras, &block)
+        end
+
+        # Stable text fingerprint for one paragraph. Identical text
+        # produces identical fingerprints.
+        #
+        # @param paragraph [Wordprocessingml::Paragraph]
+        # @return [String]
+        def fingerprint(paragraph)
+          (paragraph&.text || "").to_s
+        end
+
+        # DP LCS alignment of two arrays of fingerprints. Returns a
+        # list of `[old_idx, new_idx]` pairs:
+        #   - matching pair `[i, j]` when keys are equal
+        #   - `[i, nil]` when old[i] is removed
+        #   - `[nil, j]` when new[j] is added
+        #
+        # @param old_keys [Array<String>]
+        # @param new_keys [Array<String>]
+        # @return [Array<Array(Integer, Integer)>]
+        def align(old_keys, new_keys)
+          lcs_pairs = lcs_match_pairs(old_keys, new_keys)
+          pairs = []
+          i = 0
+          j = 0
+          lcs_pairs.each do |mi, mj|
+            while i < mi
+              pairs << [i, nil]
+              i += 1
+            end
+            while j < mj
+              pairs << [nil, j]
+              j += 1
+            end
+            pairs << [mi, mj]
+            i = mi + 1
+            j = mj + 1
+          end
+          while i < old_keys.length
+            pairs << [i, nil]
+            i += 1
+          end
+          while j < new_keys.length
+            pairs << [nil, j]
+            j += 1
+          end
+          pairs
+        end
+
+        # DP LCS: returns the list of matching (i, j) pairs in order.
+        #
+        # @param a [Array<String>]
+        # @param b [Array<String>]
+        # @return [Array<Array(Integer, Integer)>]
+        def lcs_match_pairs(a, b)
+          n = a.length
+          m = b.length
+          dp = Array.new(n + 1) { Array.new(m + 1, 0) }
+          (1..n).each do |i|
+            (1..m).each do |j|
+              dp[i][j] = if a[i - 1] == b[j - 1]
+                           dp[i - 1][j - 1] + 1
+                         else
+                           [dp[i - 1][j], dp[i][j - 1]].max
+                         end
+            end
+          end
+          backtrack(dp, a, b, n, m)
+        end
+
+        # Backtrack through the DP table to recover matching pairs.
+        def backtrack(dp, a, b, i, j)
+          return [] if i.zero? || j.zero?
+
+          if a[i - 1] == b[j - 1]
+            backtrack(dp, a, b, i - 1, j - 1) << [i - 1, j - 1]
+          elsif dp[i - 1][j] >= dp[i][j - 1]
+            backtrack(dp, a, b, i - 1, j)
+          else
+            backtrack(dp, a, b, i, j - 1)
+          end
+        end
+
+        def emit_changes(alignment, old_paras, new_paras)
+          collapsed = collapse_remove_add_pairs(alignment)
+          collapsed.each do |old_idx, new_idx|
+            case [old_idx.nil?, new_idx.nil?]
+            when [true, false]
+              yield Change.new(kind: :added, new_index: new_idx,
+                               description: "Paragraph #{new_idx + 1} added")
+            when [false, true]
+              yield Change.new(kind: :removed, old_index: old_idx,
+                               description: "Paragraph #{old_idx + 1} removed")
+            when [false, false]
+              next if identical?(old_paras[old_idx], new_paras[new_idx])
+
+              yield classify_modified(old_paras[old_idx],
+                                      new_paras[new_idx],
+                                      old_idx, new_idx)
+            end
+          end
+        end
+
+        # Collapse adjacent `[i, nil], [nil, j]` pairs into `[i, j]`
+        # modified pairs. Without this, text edits show as one remove
+        # + one add instead of one modification.
+        #
+        # @param alignment [Array<Array(Integer, Integer)>]
+        # @return [Array<Array(Integer, Integer)>]
+        def collapse_remove_add_pairs(alignment)
+          result = []
+          i = 0
+          while i < alignment.length
+            curr = alignment[i]
+            nxt = alignment[i + 1]
+            if curr[0] && curr[1].nil? && nxt && nxt[0].nil? && nxt[1]
+              result << [curr[0], nxt[1]]
+              i += 2
+            else
+              result << curr
+              i += 1
+            end
+          end
+          result
+        end
+
+        # Two paragraphs are identical when their full XML is byte-
+        # equal — same text AND same formatting AND same structure.
+        def identical?(old_para, new_para)
+          old_para.to_xml == new_para.to_xml
+        end
+
+        # Classify a modified pair by what changed.
+        def classify_modified(old_para, new_para, old_idx, new_idx)
+          modifier = modifier_for(old_para, new_para)
+          Change.new(
+            kind: :modified,
+            modifier: modifier,
+            old_index: old_idx,
+            new_index: new_idx,
+            description: "Paragraph #{old_idx + 1} -> #{new_idx + 1} " \
+                         "(#{modifier})",
+          )
+        end
+
+        # Decide what changed between two paragraphs with the same
+        # text but different XML.
+        def modifier_for(old_para, new_para)
+          return :text if old_para.text != new_para.text
+
+          old_xml = old_para.to_xml
+          new_xml = new_para.to_xml
+          return :format if format_only_change?(old_xml, new_xml)
+
+          :structure
+        end
+
+        # Heuristic: a format-only change alters rPr but not run
+        # structure. True when removing all `<w:rPr>...</w:rPr>`
+        # blocks equalizes the XML.
+        def format_only_change?(old_xml, new_xml)
+          stripped_old = old_xml.gsub(%r{<w:rPr>.*?</w:rPr>}m, "")
+          stripped_new = new_xml.gsub(%r{<w:rPr>.*?</w:rPr>}m, "")
+          stripped_old == stripped_new
+        end
+      end
+    end
+  end
+end

data/lib/uniword/diff/semantic/result.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Diff
+    module Semantic
+      # Aggregated semantic diff result. Counts by kind and modifier;
+      # full change list.
+      class Result
+        attr_reader :changes
+
+        def initialize
+          @changes = []
+        end
+
+        # @param change [Change]
+        # @return [void]
+        def add(change)
+          @changes << change
+        end
+
+        # Count by kind (`:added`, `:removed`, `:modified`, `:moved`).
+        #
+        # @return [Hash{Symbol => Integer}]
+        def by_kind
+          @changes.group_by(&:kind).transform_values(&:count)
+        end
+
+        # For modified changes, count by modifier (`:text`,
+        # `:format`, `:structure`).
+        #
+        # @return [Hash{Symbol => Integer}]
+        def by_modifier
+          modified = @changes.select { |c| c.kind == :modified }
+          modified.group_by(&:modifier).transform_values(&:count)
+        end
+
+        # Total change count.
+        #
+        # @return [Integer]
+        def count
+          @changes.length
+        end
+
+        # True when no changes.
+        #
+        # @return [Boolean]
+        def empty?
+          @changes.empty?
+        end
+      end
+    end
+  end
+end

data/lib/uniword/diff/semantic.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Diff
+    # Element-level semantic diff. Builds on the existing
+    # DocumentDiffer (paragraph LCS) to produce a structured change
+    # report where each change has a classification:
+    #
+    # - `:added` — element only in new
+    # - `:removed` — element only in old
+    # - `:modified` — element in both but different; sub-classified
+    #   by what changed (`:text`, `:format`, `:structure`)
+    # - `:moved` — element in both, same content, different position
+    #
+    # Open/closed: a new element kind to compare (images, tables,
+    # styles) = a new `Comparator` subclass + registration in
+    # `Engine::COMPARATORS`.
+    module Semantic
+      autoload :Engine, "#{__dir__}/semantic/engine"
+      autoload :Change, "#{__dir__}/semantic/change"
+      autoload :Result, "#{__dir__}/semantic/result"
+      autoload :ParagraphComparator,
+               "#{__dir__}/semantic/paragraph_comparator"
+    end
+  end
+end

data/lib/uniword/diff.rb

@@ -19,5 +19,6 @@ module Uniword
     autoload :OpcIssue, "uniword/diff/package_diff_result"
     autoload :PartChange, "uniword/diff/package_diff_result"
     autoload :PackageDiffResult, "uniword/diff/package_diff_result"
+    autoload :Semantic, "uniword/diff/semantic"
   end
 end

data/lib/uniword/docx/package_defaults.rb

@@ -112,7 +112,7 @@ module Uniword
           rels = Ooxml::Relationships::PackageRelationships.new
           rels.relationships = part_keys.each_with_index.map do |key, idx|
             defn = Ooxml::PartRegistry.find_by_key(key)
-            Ooxml::Relationships::Relationship.new(
+            Ooxml::Relationships::PackageRelationship.new(
               id: "rId#{idx + 1}",
               type: defn.rel_type,
               target: defn.target,

data/lib/uniword/docx/package_serialization.rb

@@ -260,7 +260,7 @@ document_rels)
 
         # The reconciler runs before injection; register the rId with
         # the allocator (single authority) and append the rel here.
-        package_rels.relationships << Ooxml::Relationships::Relationship.new(
+        package_rels.relationships << Ooxml::Relationships::PackageRelationship.new(
           id: allocator.alloc_rid(target: definition.target,
                                   type: definition.rel_type,
                                   scope: :package),

data/lib/uniword/docx/reconciler/helpers.rb

@@ -236,7 +236,7 @@ module Uniword
         def build_rel(id, type, target, target_mode: nil)
           attrs = { id: id, type: type, target: target }
           attrs[:target_mode] = target_mode if target_mode
-          Ooxml::Relationships::Relationship.new(**attrs)
+          Ooxml::Relationships::PackageRelationship.new(**attrs)
         end
 
         def run_properties_match?(a, b)

data/lib/uniword/docx/reconciler/referential_integrity.rb

@@ -317,7 +317,7 @@ module Uniword
           new_rid = allocator.alloc_rid(target: url, type: rel_type,
                                         target_mode: "External")
           unless valid_rids.include?(new_rid)
-            rels.relationships << Ooxml::Relationships::Relationship.new(
+            rels.relationships << Ooxml::Relationships::PackageRelationship.new(
               id: new_rid,
               type: rel_type,
               target: url,

data/lib/uniword/find_replace/scope.rb

@@ -38,9 +38,8 @@ module Uniword
       protected
 
       # Yield every Text element inside a run. A run carries its
-      # `<w:t>` Text element on the `text` accessor (lutaml-model
-      # returns the instance directly even when the attribute is
-      # declared as a collection).
+      # `<w:t>` Text elements on the `text` accessor (declared as a
+      # collection; lutaml-model 0.8.32+ returns an Array).
       #
       # @param run [Wordprocessingml::Run, nil]
       # @yieldparam text_element [Wordprocessingml::Text]
@@ -49,14 +48,13 @@ module Uniword
       def each_text_in_run(run)
         return unless run
 
-        text_element = run.text
-        return unless text_element
-
-        accessor = TextAccessor.new(
-          -> { text_element.content },
-          ->(value) { text_element.content = value },
-        )
-        yield text_element, accessor
+        run.text&.each do |text_element|
+          accessor = TextAccessor.new(
+            -> { text_element.content },
+            ->(value) { text_element.content = value },
+          )
+          yield text_element, accessor
+        end
       end
 
       # Walk every paragraph in `containers` and yield each run's

data/lib/uniword/ooxml/package_file.rb

@@ -86,7 +86,7 @@ module Uniword
         # Ensure output directory exists
         FileUtils.mkdir_p(File.dirname(output_path))
 
-        Zip::File.open(output_path, Zip::File::CREATE) do |zipfile|
+        Zip::File.open(output_path, create: true) do |zipfile|
           Dir.glob(File.join(@extracted_dir, "**", "*")).each do |file_path|
             next if File.directory?(file_path)
 

data/lib/uniword/picture/fill_rect.rb

@@ -7,7 +7,7 @@ module Uniword
     # Fill rectangle insets
     #
     # Generated from OOXML schema: picture.yml
-    # Element: <pic:fillRect>
+    # Element: <a:fillRect> (child of a:stretch in CT_BlipFillProperties)
     class FillRect < Lutaml::Model::Serializable
       attribute :l, :integer
       attribute :t, :integer
@@ -16,7 +16,7 @@ module Uniword
 
       xml do
         element "fillRect"
-        namespace Uniword::Ooxml::Namespaces::Picture
+        namespace Uniword::Ooxml::Namespaces::DrawingML
 
         map_attribute "l", to: :l
         map_attribute "t", to: :t

data/lib/uniword/picture/picture_source_rect.rb

@@ -7,7 +7,8 @@ module Uniword
     # Source rectangle for picture cropping
     #
     # Generated from OOXML schema: picture.yml
-    # Element: <pic:srcRect>
+    # Element: <a:srcRect> (CT_BlipFillProperties reuses DrawingML
+    # children inside pic:blipFill)
     class PictureSourceRect < Lutaml::Model::Serializable
       attribute :l, :integer
       attribute :t, :integer
@@ -16,7 +17,7 @@ module Uniword
 
       xml do
         element "srcRect"
-        namespace Uniword::Ooxml::Namespaces::Picture
+        namespace Uniword::Ooxml::Namespaces::DrawingML
 
         map_attribute "l", to: :l
         map_attribute "t", to: :t

data/lib/uniword/picture/picture_stretch.rb

@@ -7,13 +7,14 @@ module Uniword
     # Stretch fill properties
     #
     # Generated from OOXML schema: picture.yml
-    # Element: <pic:stretch>
+    # Element: <a:stretch> (CT_BlipFillProperties reuses DrawingML
+    # children inside pic:blipFill)
     class PictureStretch < Lutaml::Model::Serializable
       attribute :fill_rect, FillRect
 
       xml do
         element "stretch"
-        namespace Uniword::Ooxml::Namespaces::Picture
+        namespace Uniword::Ooxml::Namespaces::DrawingML
         mixed_content
 
         map_element "fillRect", to: :fill_rect, render_nil: false

data/lib/uniword/picture/tile.rb

@@ -7,7 +7,8 @@ module Uniword
     # Tile properties for picture fill
     #
     # Generated from OOXML schema: picture.yml
-    # Element: <pic:tile>
+    # Element: <a:tile> (CT_BlipFillProperties reuses DrawingML
+    # children inside pic:blipFill)
     class Tile < Lutaml::Model::Serializable
       attribute :tx, :integer
       attribute :ty, :integer
@@ -17,7 +18,7 @@ module Uniword
 
       xml do
         element "tile"
-        namespace Uniword::Ooxml::Namespaces::Picture
+        namespace Uniword::Ooxml::Namespaces::DrawingML
 
         map_attribute "tx", to: :tx
         map_attribute "ty", to: :ty

data/lib/uniword/plugin/cli_command.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Plugin
+    # Base class for plugin-provided CLI commands. A plugin CLI
+    # command is a Thor subclass that the main CLI registers as a
+    # subcommand.
+    #
+    # Subclasses declare `subcommand_name` (the name CLI users type)
+    # and `description` (shown in `uniword help`).
+    class CliCommand
+      class << self
+        # @return [Symbol] subcommand name (e.g. :myplugin)
+        def subcommand_name
+          raise NotImplementedError
+        end
+
+        # @return [String] one-line description
+        def description
+          raise NotImplementedError
+        end
+
+        # @return [Class<Thor>] the Thor subclass to register
+        def thor_class
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/uniword/plugin/loader.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Plugin
+    # Discovers plugins from installed gems. Each plugin ships a
+    # ruby file under `uniword/plugin/<name>.rb` that registers
+    # itself with `Plugin::Registry` on load.
+    class Loader
+      GLOB = "uniword/plugin/*.rb"
+
+      class << self
+        # Load every plugin file found in installed gems.
+        #
+        # @return [Array<String>] paths loaded
+        def load_all
+          Gem.find_files(GLOB).each { |path| require path }
+        end
+
+        # Run every registered transformer whose `stages` include
+        # `stage`, in registration order.
+        #
+        # @param document [Wordprocessingml::DocumentRoot]
+        # @param stage [Symbol] one of `Transformer::STAGES`
+        # @return [void]
+        def run_transformers(document:, stage:)
+          Registry.transformers.each_value do |transformer|
+            next unless transformer.applies_to?(stage)
+
+            transformer.transform(document)
+          end
+        end
+
+        # Yield every registered validator in registration order.
+        #
+        # @yieldparam validator [Plugin::Validator]
+        # @return [void]
+        def each_validator(&block)
+          Registry.validators.each_value(&block)
+        end
+      end
+    end
+  end
+end

data/lib/uniword/plugin/registry.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Plugin
+    # Central registry for installed plugins. Each plugin registers
+    # its extension surface (validator, transformer, cli command) by
+    # name; lookup is by name or by class.
+    #
+    # Open/closed: new extension surfaces = new methods on this
+    # class. Existing entries untouched.
+    class Registry
+      @validators = {}
+      @transformers = {}
+      @cli_commands = {}
+
+      class << self
+        # @return [Hash{Symbol => Plugin::Validator}]
+        attr_reader :validators
+
+        # @return [Hash{Symbol => Plugin::Transformer}]
+        attr_reader :transformers
+
+        # @return [Hash{Symbol => Plugin::CliCommand}]
+        attr_reader :cli_commands
+
+        # Register a validator. Append-only; duplicate name raises.
+        #
+        # @param name [Symbol]
+        # @param validator [Plugin::Validator]
+        # @return [void]
+        def register_validator(name, validator)
+          raise ArgumentError, "name must be a Symbol" unless name.is_a?(Symbol)
+          unless validator.is_a?(Validator)
+            raise ArgumentError,
+                  "validator must be a Validator"
+          end
+
+          @validators[name] = validator
+        end
+
+        # Register a transformer.
+        #
+        # @param name [Symbol]
+        # @param transformer [Plugin::Transformer]
+        # @return [void]
+        def register_transformer(name, transformer)
+          raise ArgumentError, "name must be a Symbol" unless name.is_a?(Symbol)
+          unless transformer.is_a?(Transformer)
+            raise ArgumentError,
+                  "transformer must be a Transformer"
+          end
+
+          @transformers[name] = transformer
+        end
+
+        # Register a CLI command (a Thor subclass).
+        #
+        # @param name [Symbol]
+        # @param command_class [Class]
+        # @return [void]
+        def register_cli_command(name, command_class)
+          raise ArgumentError, "name must be a Symbol" unless name.is_a?(Symbol)
+          unless command_class.is_a?(Class)
+            raise ArgumentError,
+                  "command_class must be a Class"
+          end
+
+          @cli_commands[name] = command_class
+        end
+
+        # Clear every registry. Used between tests and by
+        # `Configuration#reset!`.
+        #
+        # @return [void]
+        def clear
+          @validators.clear
+          @transformers.clear
+          @cli_commands.clear
+        end
+      end
+    end
+  end
+end

data/lib/uniword/plugin/transformer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Plugin
+    # Base class for plugin-provided document transformers.
+    # Subclasses implement `#transform(document)` which mutates the
+    # document in place.
+    #
+    # Pipelines call transformers at defined stages; see
+    # `Plugin.transform_for_stage`.
+    class Transformer
+      STAGES = %i[after_load before_save after_reconcile].freeze
+
+      # @return [Symbol] transformer name
+      attr_reader :name
+
+      # @return [Array<Symbol>] stages when this transformer runs
+      attr_reader :stages
+
+      # @param name [Symbol]
+      # @param stages [Array<Symbol>, Symbol] one or more of
+      #   STAGES; defaults to `:before_save`
+      def initialize(name:, stages: :before_save)
+        @name = name
+        @stages = Array(stages)
+        unknown = @stages - STAGES
+        return if unknown.empty?
+
+        raise ArgumentError,
+              "unknown stages: #{unknown.inspect}; valid: #{STAGES.inspect}"
+      end
+
+      # True when this transformer runs at the given stage.
+      #
+      # @param stage [Symbol]
+      # @return [Boolean]
+      def applies_to?(stage)
+        @stages.include?(stage)
+      end
+
+      # Mutate the document. Subclasses override.
+      #
+      # @param document [Wordprocessingml::DocumentRoot]
+      # @return [void]
+      def transform(document)
+        raise NotImplementedError
+      end
+    end
+  end
+end