uniword 1.5.2 → 1.5.4

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/properties/word2010_id_value.rb

@@ -4,13 +4,13 @@ require "lutaml/model"
 
 module Uniword
   module Properties
-    # Namespaced custom type for Word 2010 (wp14) attributes
+    # Namespaced custom type for Word 2010 Drawing (wp14) attributes
     # Used for wp14:anchorId and wp14:editId attributes
     class Word2010IdValue < Lutaml::Model::Type::String
       include Lutaml::Xml::Type::Configurable
 
       xml do
-        namespace Uniword::Ooxml::Namespaces::Word2010
+        namespace Uniword::Ooxml::Namespaces::Word2010Drawing
       end
     end
   end

data/lib/uniword/version.rb

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

data/lib/uniword/wordprocessingml/body.rb

@@ -32,15 +32,54 @@ module Uniword
         map_element "bookmarkEnd", to: :bookmark_ends, render_nil: false
       end
 
-      # Get all elements in body
+      # Get all elements in body, in document order.
       #
-      # @return [Array<Paragraph, Table, SectionProperties, StructuredDocumentTag>] All block-level content
+      # Walks `element_order` (populated by lutaml-model when mixed_content
+      # is parsed) and dispatches each tag to its typed collection —
+      # `p` -> paragraphs, `tbl` -> tables, `sdt` -> structured_document_tags,
+      # `bookmarkStart` -> bookmark_starts, `bookmarkEnd` -> bookmark_ends,
+      # `sectPr` -> section_properties. Whitespace/comment entries are
+      # skipped. Elements not represented in `element_order` are appended
+      # at the end in collection order (the only order available when
+      # `element_order` is empty or nil).
+      #
+      # @return [Array] Block-level content in document order
       def elements
+        return concatenate_typed_collections if element_order.nil? || element_order.empty?
+
         result = []
-        result.concat(paragraphs || [])
-        result.concat(structured_document_tags || [])
-        result.concat(tables || [])
-        result << section_properties if section_properties
+        counters = Hash.new(0)
+        sectpr_seen = false
+        collections = {
+          "p" => paragraphs,
+          "tbl" => tables,
+          "sdt" => structured_document_tags,
+          "bookmarkStart" => bookmark_starts,
+          "bookmarkEnd" => bookmark_ends,
+        }
+
+        element_order.each do |entry|
+          name = entry.name
+          if collections.key?(name)
+            collection = collections[name]
+            index = counters[name]
+            if collection && index < collection.size
+              result << collection[index]
+              counters[name] = index + 1
+            end
+          elsif name == "sectPr"
+            sectpr_seen = true
+            result << section_properties if section_properties
+          end
+        end
+
+        collections.each do |name, collection|
+          next unless collection && counters[name] < collection.size
+
+          result.concat(collection[counters[name]..])
+        end
+
+        result << section_properties if section_properties && !sectpr_seen
         result
       end
 
@@ -80,6 +119,15 @@ module Uniword
 
       private
 
+      def concatenate_typed_collections
+        result = []
+        result.concat(paragraphs || [])
+        result.concat(structured_document_tags || [])
+        result.concat(tables || [])
+        result << section_properties if section_properties
+        result
+      end
+
       def sync_element_order
         return if element_order.nil? || element_order.empty?
 

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/wordprocessingml/styles_configuration.rb

@@ -157,7 +157,7 @@ module Uniword
       #
       # @return [Array<Style>] Custom styles
       def custom_styles
-        styles.select(&:custom)
+        styles.select(&:custom?)
       end
 
       # Get the number of styles

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.4
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-31 00:00:00.000000000 Z
+date: 2026-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -92,14 +92,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.3'
+        version: '3.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.3'
+        version: '3.4'
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -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