uniword 1.5.2 → 1.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9574cce7758124ff340199b7b07e95bc332e86ed1428e663eff2ff5059bc044
-  data.tar.gz: 2d80ed18e0289d232422c9c882201eeed2cded201df55c3ae887945b1ec9d0bf
+  metadata.gz: 8d06b448460972e577f4d1f22b11441d07949397a06fbe9002db6c4e71d091cc
+  data.tar.gz: ae04c58467dd36288a5fdf08662496c5d99d2b2da1a7c8fa648fbedd234d9ad2
 SHA512:
-  metadata.gz: 05f384f87289e6325f6761a90afec1f08a9129bfe09b4b1bc381b0dd23bb6acd81f438f423c7463f3b609dba2c81d12ef3a6eef900b766816c69bcecb2a24c80
-  data.tar.gz: 185871d7a5926e6b1e4708cbf24169642cc4e4096edd416f184399c887ef4a6c3db40bb3dc88f3b7fb025c7826bf2a23aa86b13b9e8660ce95f35272d0282f56
+  metadata.gz: 4d3146558aaf9df9228b7d54064b31aa5c050b3262542aae4075dbeddedea6c53b864c5bc41b065d26289f9c2196e8ee331ca24893b26bea0212f32b39c3fe34
+  data.tar.gz: fcfa682da31b88784fd3ccabd152f5271f307f6046e5572093bc04789777c1dac23008ad8794d664282128301671c33b411660d5b12cdd5562773481e2adcc48

data/CHANGELOG.md

@@ -10,6 +10,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `Uniword::Caption` module — auto-numbered figure/table/equation
+  captions with `Caption::Counter`, `Caption::CaptionBuilder`
+  (SEQ field + bookmark), and `Caption::CrossReference` (REF
+  fldSimple).
+- `DocumentRoot#caption_counter`, `#add_caption(label:, text:,`
+  ` separator:)`, `#cross_reference_to(bookmark_name)` Ruby API.
+- `Uniword::Plugin` module — extensibility surface with
+  `Plugin::Validator`, `Plugin::Transformer`, `Plugin::CliCommand`
+  base classes and `Plugin::Registry` for registration.
+  `Plugin::Loader` discovers plugins via `Gem.find_files`.
+- `Uniword::Diff::Semantic` module — element-level diff with
+  change classification (`:added`, `:removed`, `:modified`, `:moved`)
+  and sub-classification for modifications (`:text`, `:format`,
+  `:structure`). LCS-based paragraph alignment.
+- `Uniword::Batch::Operation` module — parallel-by-design runner
+  for batch CLI operations. Includes `RepairTask` and `VerifyTask`;
+  extensible via `Operation::Task` subclass + `Operation::Runner`.
+
+### Changed
+
+- `Uniword::Diff` module now autoloads `Semantic` (element-level
+  diff sits alongside the existing text-level `DocumentDiffer`).
+- `Uniword::Batch` module now autoloads `Operation` (sibling to
+  the existing staged-pipeline `DocumentProcessor`).
+
+### Added (from prior PR — kept here for Unreleased record)
+
 - `DocumentRoot#find_replace(pattern, replacement, scope:, ignore_case:)`
   — Word's Home → Replace dialog as an API. Replaces every
   non-overlapping match across one or more scopes (`body`, `headers`,

data/lib/uniword/batch/operation/file_result.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Batch
+    module Operation
+      # Aggregated result for one file in a batch run.
+      class FileResult
+        # @return [String] absolute or relative path of the input file
+        attr_reader :path
+
+        # @return [Symbol] :success, :failure
+        attr_reader :status
+
+        # @return [Integer] operation-specific metric (e.g. repair
+        #   count, verify issue count)
+        attr_reader :metric
+
+        # @return [String, nil] error message when status is :failure
+        attr_reader :error
+
+        # @param path [String]
+        # @param status [Symbol]
+        # @param metric [Integer]
+        # @param error [String, nil]
+        def initialize(path:, status:, metric: 0, error: nil)
+          @path = path
+          @status = status
+          @metric = metric
+          @error = error
+        end
+
+        # @return [Boolean]
+        def success?
+          @status == :success
+        end
+      end
+    end
+  end
+end

data/lib/uniword/batch/operation/repair_task.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Batch
+    module Operation
+      # `uniword repair` for one file. Saves the repaired copy to
+      # `output_path`, returns the count of applied fixes as the
+      # metric.
+      class RepairTask < Task
+        # @param output_dir [String] directory to write repaired copies
+        def initialize(output_dir:)
+          @output_dir = output_dir
+        end
+
+        # @return [Symbol]
+        def name
+          :repair
+        end
+
+        # @param path [String]
+        # @return [FileResult]
+        def run(path)
+          doc = Uniword::DocumentFactory.from_file(path)
+          output_path = File.join(@output_dir, File.basename(path))
+
+          doc.save(output_path)
+          success(path: path)
+        rescue StandardError => e
+          failure(path: path, error: message_of(e))
+        end
+      end
+    end
+  end
+end

data/lib/uniword/batch/operation/report.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Batch
+    module Operation
+      # Aggregated report for a batch run.
+      class Report
+        attr_reader :results, :operation_name
+
+        # @param operation_name [Symbol]
+        def initialize(operation_name:)
+          @operation_name = operation_name
+          @results = []
+        end
+
+        # @param result [FileResult]
+        # @return [void]
+        def add(result)
+          @results << result
+        end
+
+        # Total file count processed.
+        #
+        # @return [Integer]
+        def count
+          @results.length
+        end
+
+        # Count of successful files.
+        #
+        # @return [Integer]
+        def success_count
+          @results.count(&:success?)
+        end
+
+        # Count of failed files.
+        #
+        # @return [Integer]
+        def failure_count
+          @results.count { |r| !r.success? }
+        end
+
+        # Sum of per-file metrics (e.g. total repairs applied).
+        #
+        # @return [Integer]
+        def total_metric
+          @results.sum(&:metric)
+        end
+
+        # True when every file succeeded.
+        #
+        # @return [Boolean]
+        def all_success?
+          @results.all?(&:success?)
+        end
+
+        # List of failed file paths.
+        #
+        # @return [Array<String>]
+        def failed_paths
+          @results.reject(&:success?).map(&:path)
+        end
+      end
+    end
+  end
+end

data/lib/uniword/batch/operation/runner.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Batch
+    module Operation
+      # Parallel runner for a Task across many files.
+      #
+      class Runner
+        # @param task [Task]
+        # @param paths [Array<String>]
+        def initialize(task:, paths:)
+          @task = task
+          @paths = paths
+        end
+
+        # Run the task on every path. Files are processed serially
+        # in v1 (parallelism deferred — see TODO.tier-2/10).
+        #
+        # @return [Report]
+        def run
+          report = Report.new(operation_name: @task.name)
+          @paths.each do |path|
+            report.add(@task.run(path))
+          end
+          report
+        end
+      end
+    end
+  end
+end

data/lib/uniword/batch/operation/task.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Batch
+    module Operation
+      # Abstract base class for one batchable operation on one file.
+      # Subclasses implement `run(path) -> FileResult`.
+      class Task
+        # @return [Symbol] task name shown in reports
+        def name
+          raise NotImplementedError
+        end
+
+        # Run the operation on one file. Returns a FileResult.
+        #
+        # @param path [String] input file path
+        # @return [FileResult]
+        def run(path)
+          raise NotImplementedError
+        end
+
+        protected
+
+        def success(path:, metric: 0)
+          FileResult.new(path: path, status: :success, metric: metric)
+        end
+
+        def failure(path:, error:, metric: 0)
+          FileResult.new(path: path, status: :failure,
+                         metric: metric, error: error)
+        end
+
+        # Render an exception's message (stripping noisy backtrace).
+        def message_of(error)
+          "#{error.class}: #{error.message}"
+        end
+      end
+    end
+  end
+end

data/lib/uniword/batch/operation/verify_task.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Batch
+    module Operation
+      # `uniword verify` for one file. Returns the issue count as the
+      # metric (0 means clean).
+      class VerifyTask < Task
+        # @return [Symbol]
+        def name
+          :verify
+        end
+
+        # @param path [String]
+        # @return [FileResult]
+        def run(path)
+          report = Uniword::Verification.verify(path)
+          issue_count = report.issues.length
+          status = report.valid? ? :success : :failure
+          FileResult.new(path: path, status: status, metric: issue_count)
+        rescue StandardError => e
+          failure(path: path, error: message_of(e))
+        end
+      end
+    end
+  end
+end

data/lib/uniword/batch/operation.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Batch
+    # Operation-style batching: run a top-level CLI operation
+    # (repair, verify, find-replace, diff) across many files in
+    # parallel with structured per-file reports. Distinct from
+    # `Batch::DocumentProcessor` (staged pipeline processing) and
+    # from `Batch::ProcessingStage`.
+    #
+    # Open/closed: a new operation = new subclass of `Operation::Task`
+    # + registration in `Operation::Runner::TASKS`.
+    module Operation
+      autoload :Task, "#{__dir__}/operation/task"
+      autoload :FileResult, "#{__dir__}/operation/file_result"
+      autoload :Report, "#{__dir__}/operation/report"
+      autoload :Runner, "#{__dir__}/operation/runner"
+      autoload :RepairTask, "#{__dir__}/operation/repair_task"
+      autoload :VerifyTask, "#{__dir__}/operation/verify_task"
+    end
+  end
+end

data/lib/uniword/batch.rb

@@ -15,5 +15,6 @@ module Uniword
     autoload :UpdateMetadataStage,
              "#{__dir__}/batch/stages/update_metadata_stage"
     autoload :ValidateLinksStage, "#{__dir__}/batch/stages/validate_links_stage"
+    autoload :Operation, "#{__dir__}/batch/operation"
   end
 end

data/lib/uniword/caption/caption_builder.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Caption
+    # Builds a Caption-styled paragraph for one caption.
+    #
+    # Layout of the produced paragraph:
+    #
+    #   <w:p>
+    #     <w:pPr><w:pStyle w:val="Caption"/></w:pPr>
+    #     <w:bookmarkStart w:id="N" w:name="_Figure1"/>
+    #     <w:r><w:t xml:space="preserve">Figure </w:t></w:r>
+    #     <w:fldSimple w:instr=" SEQ Figure \* ARABIC ">
+    #       <w:r><w:t>1</w:t></w:r>
+    #     </w:fldSimple>
+    #     <w:r><w:t xml:space="preserve">: Caption text</w:t></w:r>
+    #     <w:bookmarkEnd w:id="N"/>
+    #   </w:p>
+    #
+    # The bookmark name is `_Figure1`, `_Table2`, etc. — `_` prefix
+    # matches Word's convention for hidden bookmarks.
+    class CaptionBuilder
+      DEFAULT_SEPARATOR = ": "
+
+      # @param counter [Counter]
+      def initialize(counter)
+        @counter = counter
+      end
+
+      # Build a caption paragraph.
+      #
+      # @param label [String] e.g. "Figure"
+      # @param text [String] caption body text
+      # @param separator [String] between label/number and body
+      #   (default ": ")
+      # @param bookmark_id [Integer, nil] bookmark id; auto-allocated
+      #   when nil
+      # @return [Array<Wordprocessingml::Paragraph, String>] the
+      #   paragraph and the bookmark name (caller appends the
+      #   paragraph to the document)
+      def build(label:, text:, separator: DEFAULT_SEPARATOR,
+                bookmark_id: nil)
+        sequence = @counter.next_value(label)
+        bookmark_name = bookmark_name_for(label, sequence)
+        bookmark_id ||= sequence
+
+        [
+          build_paragraph(label: label,
+                          sequence: sequence,
+                          text: text,
+                          separator: separator,
+                          bookmark_name: bookmark_name,
+                          bookmark_id: bookmark_id),
+          bookmark_name,
+        ]
+      end
+
+      private
+
+      def build_paragraph(label:, sequence:, text:, separator:,
+                          bookmark_name:, bookmark_id:)
+        para = Wordprocessingml::Paragraph.new
+        para.properties = paragraph_properties
+        para.bookmark_starts = [start_bookmark(bookmark_id, bookmark_name)]
+        para.runs = [
+          label_run("#{label} "),
+          seq_field(label, sequence),
+          body_run("#{separator}#{text}"),
+        ]
+        para.bookmark_ends = [end_bookmark(bookmark_id)]
+        para
+      end
+
+      def paragraph_properties
+        props = Wordprocessingml::ParagraphProperties.new
+        props.style = "Caption"
+        props
+      end
+
+      def start_bookmark(id, name)
+        Wordprocessingml::BookmarkStart.new(id: id.to_s, name: name)
+      end
+
+      def end_bookmark(id)
+        Wordprocessingml::BookmarkEnd.new(id: id.to_s)
+      end
+
+      def label_run(text)
+        run_with_text(text)
+      end
+
+      def body_run(text)
+        run_with_text(text)
+      end
+
+      def run_with_text(text)
+        Wordprocessingml::Run.new(text: [text_element(text)])
+      end
+
+      def text_element(content)
+        Wordprocessingml::Text.new(content: content, xml_space: "preserve")
+      end
+
+      def seq_field(label, sequence)
+        Wordprocessingml::SimpleField.new(
+          instr: seq_instruction(label),
+          runs: [run_with_text(sequence.to_s)],
+        )
+      end
+
+      def seq_instruction(label)
+        " SEQ #{label} \\* ARABIC "
+      end
+
+      def bookmark_name_for(label, sequence)
+        "_#{label}#{sequence}"
+      end
+    end
+  end
+end

data/lib/uniword/caption/counter.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Caption
+    # Label-keyed counter for figure/table/equation captions.
+    # Persisted on the document via `DocumentRoot#caption_counters`;
+    # each label starts at 1 and increments on every `next_value`.
+    #
+    # Open/closed: any label string works — adding a new label
+    # category is just using it.
+    class Counter
+      # @return [Hash{String => Integer}]
+      attr_reader :counts
+
+      def initialize
+        @counts = Hash.new { |h, k| h[k] = 0 }
+      end
+
+      # @param label [String] e.g. "Figure", "Table", "Equation"
+      # @return [Integer] the next sequence value for this label
+      def next_value(label)
+        label = normalize_label(label)
+        @counts[label] += 1
+      end
+
+      # Current count without incrementing.
+      #
+      # @param label [String]
+      # @return [Integer]
+      def current(label)
+        @counts[normalize_label(label)]
+      end
+
+      # Reset one or all counters.
+      #
+      # @param label [String, nil] nil resets all
+      # @return [void]
+      def reset(label = nil)
+        if label.nil?
+          @counts.clear
+          return
+        end
+
+        @counts.delete(normalize_label(label))
+      end
+
+      # All labels currently tracked.
+      #
+      # @return [Array<String>]
+      def labels
+        @counts.keys
+      end
+
+      private
+
+      def normalize_label(label)
+        label.to_s
+      end
+    end
+  end
+end

data/lib/uniword/caption/cross_reference.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Caption
+    # Builds a `REF` fldSimple that references a bookmark, producing
+    # display text like "Figure 3" or "Table 2" when Word renders it.
+    #
+    # For Word to refresh these fields on open, set
+    # `Settings#update_fields` (the `w:updateFields` element) to
+    # `UpdateFields.new` before saving.
+    class CrossReference
+      # @param bookmark_name [String] target bookmark name
+      def initialize(bookmark_name)
+        @bookmark_name = bookmark_name
+      end
+
+      # @return [Wordprocessingml::SimpleField]
+      def build
+        Wordprocessingml::SimpleField.new(
+          instr: instruction,
+          runs: [placeholder_run],
+        )
+      end
+
+      private
+
+      # The `\h` switch makes the reference a hyperlink (clickable).
+      def instruction
+        " REF #{@bookmark_name} \\h "
+      end
+
+      def placeholder_run
+        Wordprocessingml::Run.new(text: [placeholder_text])
+      end
+
+      # Word replaces this with the bookmark's display text on
+      # field update. uniword writes the bookmark name as a
+      # placeholder so the field is never empty before refresh.
+      def placeholder_text
+        Wordprocessingml::Text.new(content: @bookmark_name)
+      end
+    end
+  end
+end

data/lib/uniword/caption.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Uniword
+  # Auto-numbered figure/table/equation captions with cross-references
+  # and Tables of Figures.
+  #
+  # Three pieces, all model-driven:
+  #
+  # - `Caption::Counter` — label-keyed counters (Figure, Table,
+  #   Equation) persisted on the document. Reset to 1 at the start
+  #   of each document load.
+  # - `Caption::CaptionBuilder` — builds a Caption-styled paragraph
+  #   with a SEQ field, returns the assigned bookmark name.
+  # - `Caption::CrossReference` — builds a REF fldSimple targeting a
+  #   named bookmark.
+  #
+  # The TOC of figures is just the existing TOC engine with `\c`
+  # instead of `\o`; see `Toc::FigureEntryBuilder`.
+  module Caption
+    autoload :Counter, "#{__dir__}/caption/counter"
+    autoload :CaptionBuilder, "#{__dir__}/caption/caption_builder"
+    autoload :CrossReference, "#{__dir__}/caption/cross_reference"
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Diff
+    module Semantic
+      # One classified change. Severity defaults to :info; classifiers
+      # can promote to :warning or :error.
+      class Change
+        KINDS = %i[added removed modified moved].freeze
+        MODIFIERS = %i[text format structure].freeze
+
+        # @return [Symbol] one of KINDS
+        attr_reader :kind
+
+        # @return [Symbol, nil] for :modified, one of MODIFIERS
+        attr_reader :modifier
+
+        # @return [Integer, nil] paragraph index in old (nil when
+        #   the paragraph is new)
+        attr_reader :old_index
+
+        # @return [Integer, nil] paragraph index in new (nil when
+        #   the paragraph was removed)
+        attr_reader :new_index
+
+        # @return [String, nil] human-readable summary
+        attr_reader :description
+
+        # @param kind [Symbol]
+        # @param modifier [Symbol, nil]
+        # @param old_index [Integer, nil]
+        # @param new_index [Integer, nil]
+        # @param description [String, nil]
+        def initialize(kind:, modifier: nil, old_index: nil,
+                       new_index: nil, description: nil)
+          unless KINDS.include?(kind)
+            raise ArgumentError,
+                  "unknown kind #{kind.inspect}"
+          end
+          if modifier && !MODIFIERS.include?(modifier)
+            raise ArgumentError, "unknown modifier #{modifier.inspect}"
+          end
+
+          @kind = kind
+          @modifier = modifier
+          @old_index = old_index
+          @new_index = new_index
+          @description = description
+        end
+
+        # @return [Hash]
+        def to_h
+          { kind: kind, modifier: modifier,
+            old_index: old_index, new_index: new_index,
+            description: description }
+        end
+
+        # @param other [Object]
+        # @return [Boolean]
+        def ==(other)
+          other.is_a?(Change) && to_h == other.to_h
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Diff
+    module Semantic
+      # Orchestrates element-level diff between two documents.
+      # Currently compares body paragraphs; future comparators
+      # (tables, images, styles) plug in via `COMPARATORS`.
+      class Engine
+        # @param old_doc [Wordprocessingml::DocumentRoot]
+        # @param new_doc [Wordprocessingml::DocumentRoot]
+        def initialize(old_doc, new_doc)
+          @old_doc = old_doc
+          @new_doc = new_doc
+        end
+
+        # Run every registered comparator and aggregate the changes.
+        #
+        # @return [Result]
+        def diff
+          result = Result.new
+          ParagraphComparator.each_change(@old_doc.paragraphs,
+                                          @new_doc.paragraphs) do |change|
+            result.add(change)
+          end
+          result
+        end
+      end
+    end
+  end
+end