uniword 1.5.2 → 1.5.3

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/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

data/lib/uniword/plugin/validator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Plugin
+    # Base class for plugin-provided validation rules. Subclasses
+    # implement `#check(document)` (yields findings).
+    #
+    # Open/closed: adding a new validator = subclassing + calling
+    # `Registry.register_validator`.
+    class Validator
+      # @return [Symbol] validator name (matches the registry key)
+      attr_reader :name
+
+      # @return [Symbol] default severity (:error, :warning, :info)
+      attr_reader :severity
+
+      # @param name [Symbol]
+      # @param severity [Symbol]
+      def initialize(name:, severity: :warning)
+        @name = name
+        @severity = severity
+      end
+
+      # Walk the document and yield each finding as a hash.
+      #
+      # @param document [Wordprocessingml::DocumentRoot]
+      # @yieldparam finding [Hash] { message:, path: }
+      # @return [void]
+      def check(document)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/uniword/plugin.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Uniword
+  # Plugin system: extend uniword without forking.
+  #
+  # Three extension surfaces, each with a base class:
+  #
+  # - `Plugin::Validator` — register custom validation rules
+  # - `Plugin::Transformer` — mutate documents at defined pipeline
+  #   stages (load, pre-save, post-reconcile)
+  # - `Plugin::CliCommand` — register new Thor subcommands
+  #
+  # Discovery: `Plugin::Loader.load_all` walks installed gems via
+  # `Gem.find_files("uniword/plugin/*.rb")` and loads each.
+  #
+  # Configuration: `Uniword.configuration.plugins = [:my_plugin]`
+  # (default `:all`).
+  module Plugin
+    autoload :Registry, "#{__dir__}/plugin/registry"
+    autoload :Validator, "#{__dir__}/plugin/validator"
+    autoload :Transformer, "#{__dir__}/plugin/transformer"
+    autoload :CliCommand, "#{__dir__}/plugin/cli_command"
+    autoload :Loader, "#{__dir__}/plugin/loader"
+  end
+end

data/lib/uniword/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Uniword
-  VERSION = "1.5.2"
+  VERSION = "1.5.3"
 end

data/lib/uniword/wordprocessingml/document_styling.rb

@@ -195,6 +195,46 @@ module Uniword
         Lint::Engine.new(document: self, ruleset: ruleset).run
       end
 
+      # Counter for auto-numbered captions. Persisted across the
+      # document's lifetime; reset on document load.
+      #
+      # @return [Caption::Counter]
+      def caption_counter
+        @caption_counter ||= Caption::Counter.new
+      end
+
+      # Add an auto-numbered caption paragraph to the body and
+      # return the bookmark name (for use in cross-references).
+      #
+      # The caption is appended as a new paragraph with style
+      # "Caption" and a SEQ field. The bookmark wraps the entire
+      # paragraph so cross-references resolve to the caption text.
+      #
+      # @param label [String] "Figure", "Table", "Equation", or any
+      #   other category — each gets its own counter
+      # @param text [String] caption body
+      # @param separator [String] between the label/number and the
+      #   body (default ": ")
+      # @return [String] bookmark name (e.g. "_Figure1")
+      def add_caption(label:, text:, separator: ": ")
+        builder = Caption::CaptionBuilder.new(caption_counter)
+        paragraph, bookmark_name = builder.build(label: label,
+                                                 text: text,
+                                                 separator: separator)
+        body.paragraphs << paragraph
+        bookmark_name
+      end
+
+      # Build a cross-reference run targeting a bookmark. Returns a
+      # Run containing a SimpleField with a REF instruction. The
+      # caller decides where to place it.
+      #
+      # @param bookmark_name [String] target bookmark
+      # @return [Wordprocessingml::SimpleField]
+      def cross_reference_to(bookmark_name)
+        Caption::CrossReference.new(bookmark_name).build
+      end
+
       # Apply uniform page setup to every section of the document
       #
       # Mirrors Word's Layout dialog: named paper sizes, orientation

data/lib/uniword.rb

@@ -140,6 +140,12 @@ module Uniword
   # Document lint (style-guide enforcement).
   autoload :Lint, "uniword/lint"
 
+  # Auto-numbered captions + cross-references.
+  autoload :Caption, "uniword/caption"
+
+  # Plugin system (validators, transformers, CLI commands).
+  autoload :Plugin, "uniword/plugin"
+
   # CLI
   autoload :CLI, "uniword/cli/main"
   autoload :GenerateCLI, "uniword/cli/generate_cli"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: uniword
 version: !ruby/object:Gem::Version
-  version: 1.5.2
+  version: 1.5.3
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-31 00:00:00.000000000 Z
+date: 2026-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -592,6 +592,13 @@ files:
 - lib/uniword/batch.rb
 - lib/uniword/batch/batch_result.rb
 - lib/uniword/batch/document_processor.rb
+- lib/uniword/batch/operation.rb
+- lib/uniword/batch/operation/file_result.rb
+- lib/uniword/batch/operation/repair_task.rb
+- lib/uniword/batch/operation/report.rb
+- lib/uniword/batch/operation/runner.rb
+- lib/uniword/batch/operation/task.rb
+- lib/uniword/batch/operation/verify_task.rb
 - lib/uniword/batch/processing_stage.rb
 - lib/uniword/batch/stages/compress_images_stage.rb
 - lib/uniword/batch/stages/convert_format_stage.rb
@@ -656,6 +663,10 @@ files:
 - lib/uniword/builder/theme_builder.rb
 - lib/uniword/builder/toc_builder.rb
 - lib/uniword/builder/watermark_builder.rb
+- lib/uniword/caption.rb
+- lib/uniword/caption/caption_builder.rb
+- lib/uniword/caption/counter.rb
+- lib/uniword/caption/cross_reference.rb
 - lib/uniword/chart.rb
 - lib/uniword/chart/area3_d_chart.rb
 - lib/uniword/chart/area_chart.rb
@@ -800,6 +811,11 @@ files:
 - lib/uniword/diff/formatter.rb
 - lib/uniword/diff/package_diff_result.rb
 - lib/uniword/diff/package_differ.rb
+- lib/uniword/diff/semantic.rb
+- lib/uniword/diff/semantic/change.rb
+- lib/uniword/diff/semantic/engine.rb
+- lib/uniword/diff/semantic/paragraph_comparator.rb
+- lib/uniword/diff/semantic/result.rb
 - lib/uniword/document_factory.rb
 - lib/uniword/document_input.rb
 - lib/uniword/document_variables.rb
@@ -1205,6 +1221,12 @@ files:
 - lib/uniword/picture/picture_source_rect.rb
 - lib/uniword/picture/picture_stretch.rb
 - lib/uniword/picture/tile.rb
+- lib/uniword/plugin.rb
+- lib/uniword/plugin/cli_command.rb
+- lib/uniword/plugin/loader.rb
+- lib/uniword/plugin/registry.rb
+- lib/uniword/plugin/transformer.rb
+- lib/uniword/plugin/validator.rb
 - lib/uniword/presentationml.rb
 - lib/uniword/presentationml/audio.rb
 - lib/uniword/presentationml/body_properties.rb