uniword 1.5.1 → 1.5.3

data/lib/uniword/find_replace/comment_scope.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Uniword
+  module FindReplace
+    # Comments scope: text in `word/comments.xml`. Walks every
+    # comment's paragraphs.
+    class CommentScope < Scope
+      # @return [Symbol]
+      def name
+        :comments
+      end
+
+      # @yieldparam text_element [Wordprocessingml::Text]
+      # @yieldparam accessor [Scope::TextAccessor]
+      def each_text_node
+        comments = @document.comments&.comments
+        return unless comments
+
+        each_text_in_containers(comments) { |*a| yield(*a) }
+      end
+    end
+  end
+end

data/lib/uniword/find_replace/endnote_scope.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Uniword
+  module FindReplace
+    # Endnotes scope: text in `word/endnotes.xml`. Walks every
+    # endnote entry's paragraphs.
+    class EndnoteScope < Scope
+      # @return [Symbol]
+      def name
+        :endnotes
+      end
+
+      # @yieldparam text_element [Wordprocessingml::Text]
+      # @yieldparam accessor [Scope::TextAccessor]
+      def each_text_node
+        entries = @document.endnotes&.endnote_entries
+        return unless entries
+
+        each_text_in_containers(entries) { |*a| yield(*a) }
+      end
+    end
+  end
+end

data/lib/uniword/find_replace/engine.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Uniword
+  module FindReplace
+    # Orchestrates a find-replace pass over a package.
+    #
+    # Owns the scope registry (which parts to scan) and matcher
+    # dispatch (literal vs regex). Returns a `Result` with total
+    # count and per-scope breakdown.
+    #
+    # Open/closed: scopes register in `SCOPE_REGISTRY`; adding one is
+    # data, not behavior. The matcher class is chosen by the
+    # `regex:` flag, but callers can pass a custom `Matcher` instance
+    # to bypass the flag entirely.
+    class Engine
+      # Symbol => Scope subclass. Adding a scope = adding an entry.
+      SCOPE_REGISTRY = {
+        body: BodyScope,
+        headers: HeaderScope,
+        footers: FooterScope,
+        footnotes: FootnoteScope,
+        endnotes: EndnoteScope,
+        comments: CommentScope,
+        styles: StylesScope,
+      }.freeze
+
+      # All registered scope names. Used by `:all` to expand.
+      ALL_SCOPES = SCOPE_REGISTRY.keys.freeze
+
+      # @param document [Wordprocessingml::DocumentRoot]
+      # @param matcher [Matcher]
+      # @param scopes [Array<Symbol>, :all] scopes to scan; `:all`
+      #   expands to every registered scope
+      def initialize(document:, matcher:, scopes: :all)
+        @document = document
+        @matcher = matcher
+        @scopes = resolve_scopes(scopes)
+      end
+
+      # Run the find-replace pass.
+      #
+      # @return [Result]
+      def run
+        result = Result.new
+        return result if @matcher.nil? || @scopes.empty?
+
+        @scopes.each do |scope_name|
+          scope_class = SCOPE_REGISTRY.fetch(scope_name)
+          scope = scope_class.new(@document)
+          substitutions_in_scope = apply_scope(scope)
+          result.add(scope_name, substitutions_in_scope)
+        end
+        result
+      end
+
+      private
+
+      def resolve_scopes(scopes)
+        return ALL_SCOPES if scopes == :all
+
+        Array(scopes).select { |s| SCOPE_REGISTRY.key?(s) }
+      end
+
+      # Apply the matcher to every text accessor in one scope.
+      #
+      # @param scope [Scope]
+      # @return [Integer] substitutions applied in this scope
+      def apply_scope(scope)
+        substitutions = 0
+        scope.each_text_node do |_holder, accessor|
+          original = accessor.value
+          next unless original
+
+          new_text, count = @matcher.apply(original)
+          next if count.zero?
+
+          accessor.value = new_text
+          substitutions += count
+        end
+        substitutions
+      end
+    end
+  end
+end

data/lib/uniword/find_replace/footer_scope.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Uniword
+  module FindReplace
+    # Footers scope: text in every `word/footer*.xml`. Walks all
+    # footer parts in the document's header-footer store.
+    class FooterScope < Scope
+      # @return [Symbol]
+      def name
+        :footers
+      end
+
+      # @yieldparam text_element [Wordprocessingml::Text]
+      # @yieldparam accessor [Scope::TextAccessor]
+      def each_text_node
+        parts = @document.header_footer_parts
+        return unless parts
+
+        containers = parts.of_kind(:footer).filter_map(&:content)
+        each_text_in_containers(containers) { |*a| yield(*a) }
+      end
+    end
+  end
+end

data/lib/uniword/find_replace/footnote_scope.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Uniword
+  module FindReplace
+    # Footnotes scope: text in `word/footnotes.xml`. Walks every
+    # footnote entry's paragraphs.
+    class FootnoteScope < Scope
+      # @return [Symbol]
+      def name
+        :footnotes
+      end
+
+      # @yieldparam text_element [Wordprocessingml::Text]
+      # @yieldparam accessor [Scope::TextAccessor]
+      def each_text_node
+        entries = @document.footnotes&.footnote_entries
+        return unless entries
+
+        each_text_in_containers(entries) { |*a| yield(*a) }
+      end
+    end
+  end
+end

data/lib/uniword/find_replace/header_scope.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Uniword
+  module FindReplace
+    # Headers scope: text in every `word/header*.xml`. Walks all
+    # header parts in the document's header-footer store.
+    class HeaderScope < Scope
+      # @return [Symbol]
+      def name
+        :headers
+      end
+
+      # @yieldparam text_element [Wordprocessingml::Text]
+      # @yieldparam accessor [Scope::TextAccessor]
+      def each_text_node
+        parts = @document.header_footer_parts
+        return unless parts
+
+        containers = parts.of_kind(:header).filter_map(&:content)
+        each_text_in_containers(containers) { |*a| yield(*a) }
+      end
+    end
+  end
+end

data/lib/uniword/find_replace/matcher.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Uniword
+  module FindReplace
+    # Abstract matcher: decides whether a string matches and what to
+    # replace it with.
+    #
+    # Subclasses implement `matches?` (returns MatchData or nil) and
+    # `substitute` (applies the replacement given MatchData). The
+    # engine drives both via `apply`, which performs one substitution
+    # pass over a single string and returns `[new_string, count]`.
+    class Matcher
+      # Apply the matcher to one string, replacing every non-overlapping
+      # match. Returns the new string and the count of substitutions.
+      #
+      # @param text [String] the text to scan
+      # @return [Array(String, Integer)] new text and substitution count
+      def apply(text)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/uniword/find_replace/paragraph_walker.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Uniword
+  module FindReplace
+    # Walks an enumerable of containers (Body, TableCell, SDT, ...)
+    # and yields every Paragraph reachable. Used by all scopes that
+    # traverse paragraph-bearing parts (body, headers, footers,
+    # footnotes, endnotes, comments).
+    module ParagraphWalker
+      module_function
+
+      # @param containers [Enumerable<#paragraphs, #tables,
+      #   #structured_document_tags>] containers to walk
+      # @yieldparam paragraph [Wordprocessingml::Paragraph]
+      # @return [void]
+      def each_paragraph(containers, &block)
+        containers.each do |container|
+          walk_container(container, &block)
+        end
+      end
+
+      # @param container [Object]
+      # @yieldparam paragraph [Wordprocessingml::Paragraph]
+      # @return [void]
+      def walk_container(container, &block)
+        container.paragraphs&.each(&block)
+        walk_tables(container.tables, &block) if container.tables
+        if container.structured_document_tags
+          walk_sdts(container.structured_document_tags, &block)
+        end
+      end
+
+      def walk_tables(tables, &block)
+        tables.each do |table|
+          walk_table_rows(table, &block) if table.rows
+        end
+      end
+
+      def walk_table_rows(table, &block)
+        table.rows.each do |row|
+          walk_table_cells(row, &block) if row.cells
+        end
+      end
+
+      def walk_table_cells(row, &block)
+        row.cells.each do |cell|
+          walk_container(cell, &block) if cell
+        end
+      end
+
+      def walk_sdts(sdts, &block)
+        sdts.each do |sdt|
+          sdt.paragraphs&.each(&block)
+        end
+      end
+
+      private_class_method :walk_container, :walk_tables, :walk_table_rows,
+                           :walk_table_cells, :walk_sdts
+    end
+  end
+end

data/lib/uniword/find_replace/regex_matcher.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Uniword
+  module FindReplace
+    # Regex matcher. Replaces every match of `pattern` with
+    # `replacement`, supporting capture-group references (`\1`,
+    # `\2`, ...) and `ignore_case`.
+    class RegexMatcher < Matcher
+      # @param pattern [Regexp, String] pattern to match. String is
+      #   compiled to a Regexp.
+      # @param replacement [String] replacement, may reference captures
+      # @param ignore_case [Boolean] force case-insensitive (only
+      #   applies when pattern is a String; Regexp keeps its own flags)
+      def initialize(pattern:, replacement:, ignore_case: false)
+        @pattern = compile_pattern(pattern, ignore_case)
+        @replacement = replacement
+      end
+
+      # @param text [String]
+      # @return [Array(String, Integer)]
+      def apply(text)
+        matches = text.scan(@pattern).size
+        return [text, 0] if matches.zero?
+
+        [text.gsub(@pattern, @replacement), matches]
+      end
+
+      private
+
+      def compile_pattern(pattern, ignore_case)
+        return pattern if pattern.is_a?(Regexp)
+        return Regexp.new(pattern, Regexp::IGNORECASE) if ignore_case
+
+        Regexp.new(pattern)
+      end
+    end
+  end
+end

data/lib/uniword/find_replace/result.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Uniword
+  module FindReplace
+    # Aggregated result of a find-replace pass.
+    #
+    # Counts total substitutions and breaks the count down by scope
+    # so callers can see where matches happened. Returned by
+    # `Engine#run` and `DocumentRoot#find_replace`.
+    #
+    # @example
+    #   result = engine.run
+    #   result.count              # => 7
+    #   result.by_scope           # => { body: 5, headers: 2 }
+    #   result.scopes_touched     # => [:body, :headers]
+    class Result
+      attr_reader :by_scope
+
+      def initialize
+        @by_scope = Hash.new { |hash, key| hash[key] = 0 }
+      end
+
+      # Increment the count for one scope.
+      #
+      # @param scope [Symbol] scope name (e.g. :body, :headers)
+      # @param substitutions [Integer] substitutions added
+      # @return [void]
+      def add(scope, substitutions)
+        @by_scope[scope] += substitutions
+      end
+
+      # Total substitutions across all scopes.
+      #
+      # @return [Integer]
+      def count
+        @by_scope.values.sum
+      end
+
+      # Scopes that produced at least one substitution.
+      #
+      # @return [Array<Symbol>]
+      def scopes_touched
+        @by_scope.select { |_, c| c.positive? }.keys
+      end
+
+      # True when zero substitutions were made.
+      #
+      # @return [Boolean]
+      def empty?
+        count.zero?
+      end
+    end
+  end
+end

data/lib/uniword/find_replace/scope.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Uniword
+  module FindReplace
+    # Abstract scope: knows how to enumerate text-bearing nodes in
+    # one part of the package and run a matcher over them.
+    #
+    # Each subclass implements `each_text_node`, yielding
+    # `[holder, accessor]` pairs where `holder` is the object whose
+    # text we read/write and `accessor` is a `TextAccessor` value
+    # object with `value` and `value=` methods.
+    #
+    # Open/closed: a new scope = a new subclass + registration in
+    # `Engine::SCOPE_REGISTRY`. Engine and other scopes are
+    # unchanged.
+    class Scope
+      # @param document [Wordprocessingml::DocumentRoot]
+      def initialize(document)
+        @document = document
+      end
+
+      # @return [Symbol] scope name (e.g. :body, :headers)
+      def name
+        raise NotImplementedError
+      end
+
+      # Yield `[holder, accessor]` for every text node this scope
+      # covers. Engine applies the matcher to each accessor.
+      #
+      # @yieldparam holder [Wordprocessingml::Text] the Text element
+      #   being read/written (its `content` attribute holds the string)
+      # @yieldparam accessor [Scope::TextAccessor]
+      # @return [void]
+      def each_text_node
+        raise NotImplementedError
+      end
+
+      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).
+      #
+      # @param run [Wordprocessingml::Run, nil]
+      # @yieldparam text_element [Wordprocessingml::Text]
+      # @yieldparam accessor [TextAccessor]
+      # @return [void]
+      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
+      end
+
+      # Walk every paragraph in `containers` and yield each run's
+      # text elements. Shared by body / headers / footers / footnotes
+      # / endnotes / comments scopes.
+      #
+      # @param containers [Enumerable<#paragraphs, #tables,
+      #   #structured_document_tags>]
+      # @yieldparam text_element [Wordprocessingml::Text]
+      # @yieldparam accessor [TextAccessor]
+      # @return [void]
+      def each_text_in_containers(containers)
+        ParagraphWalker.each_paragraph(containers) do |paragraph|
+          paragraph.runs&.each do |run|
+            each_text_in_run(run) { |*a| yield(*a) }
+          end
+        end
+      end
+
+      # Small value object with a `value` reader and `value=`
+      # writer, backed by lambdas. Avoids `instance_variable_set` /
+      # `send`; lets callers wire read/write however they like.
+      class TextAccessor
+        def initialize(reader, writer)
+          @reader = reader
+          @writer = writer
+        end
+
+        def value
+          @reader.call
+        end
+
+        def value=(new_value)
+          @writer.call(new_value)
+        end
+      end
+    end
+  end
+end

data/lib/uniword/find_replace/string_matcher.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Uniword
+  module FindReplace
+    # Literal substring matcher. Replaces every non-overlapping
+    # occurrence of `pattern` with `replacement`.
+    class StringMatcher < Matcher
+      # @param pattern [String] literal substring to find
+      # @param replacement [String] replacement text
+      # @param ignore_case [Boolean] match case-insensitively
+      def initialize(pattern:, replacement:, ignore_case: false)
+        raise ArgumentError, "pattern cannot be empty" if pattern.empty?
+
+        @pattern = pattern
+        @replacement = replacement
+        @ignore_case = ignore_case
+      end
+
+      # @param text [String]
+      # @return [Array(String, Integer)]
+      def apply(text)
+        unless text.include?(@pattern) || matches_ignore_case?(text)
+          return [text,
+                  0]
+        end
+
+        text.size
+        result = replace_all(text)
+        substitutions = count_substitutions(text, result)
+        [result, substitutions]
+      end
+
+      private
+
+      def matches_ignore_case?(text)
+        @ignore_case && text.downcase.include?(@pattern.downcase)
+      end
+
+      def replace_all(text)
+        if @ignore_case
+          pattern = /#{Regexp.escape(@pattern)}/i
+          text.gsub(pattern, @replacement)
+        else
+          text.gsub(@pattern, @replacement)
+        end
+      end
+
+      # Net change in match count from the substitution. Computed by
+      # walking the original text and counting non-overlapping
+      # matches; the gsub above cannot be relied on directly when
+      # ignore_case is on (the pattern escapes are regex-based).
+      def count_substitutions(original, _replacement)
+        pattern = @ignore_case ? /#{Regexp.escape(@pattern)}/i : nil
+        if @ignore_case
+          original.scan(pattern).size
+        else
+          count_literal(original)
+        end
+      end
+
+      def count_literal(text)
+        count = 0
+        idx = 0
+        while (idx = text.index(@pattern, idx))
+          count += 1
+          idx += @pattern.length
+        end
+        count
+      end
+    end
+  end
+end

data/lib/uniword/find_replace/styles_scope.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Uniword
+  module FindReplace
+    # Styles scope: text in style display names (`<w:name w:val=...>`
+    # inside `word/styles.xml`).
+    #
+    # Style identifiers (`w:styleId`) are deliberately not touched —
+    # renaming a styleId breaks every reference. Use
+    # `DocumentRoot#rename_style` for that, which keeps references
+    # intact.
+    class StylesScope < Scope
+      # @return [Symbol]
+      def name
+        :styles
+      end
+
+      # @yieldparam name_element [Wordprocessingml::StyleName]
+      # @yieldparam accessor [Scope::TextAccessor]
+      def each_text_node
+        styles = @document.styles_configuration&.styles
+        return unless styles
+
+        styles.each do |style|
+          name_element = style.name
+          next unless name_element
+          next unless name_element.val
+
+          accessor = TextAccessor.new(
+            -> { name_element.val },
+            ->(value) { name_element.val = value },
+          )
+          yield name_element, accessor
+        end
+      end
+    end
+  end
+end

data/lib/uniword/find_replace.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Uniword
+  # Find & replace over the text-bearing parts of a DOCX package.
+  #
+  # Public surface: `Engine` (orchestrator), `Scope` (per-part
+  # strategy), `Matcher` (literal or regex), `Result` (counts +
+  # per-scope breakdown).
+  #
+  # Open/closed: adding a new scope = new subclass of `Scope` plus
+  # registration. Adding a new matcher type = new subclass of
+  # `Matcher`. Engine unchanged in both cases.
+  module FindReplace
+    autoload :Engine, "#{__dir__}/find_replace/engine"
+    autoload :Matcher, "#{__dir__}/find_replace/matcher"
+    autoload :StringMatcher, "#{__dir__}/find_replace/string_matcher"
+    autoload :RegexMatcher, "#{__dir__}/find_replace/regex_matcher"
+    autoload :Scope, "#{__dir__}/find_replace/scope"
+    autoload :BodyScope, "#{__dir__}/find_replace/body_scope"
+    autoload :HeaderScope, "#{__dir__}/find_replace/header_scope"
+    autoload :FooterScope, "#{__dir__}/find_replace/footer_scope"
+    autoload :FootnoteScope, "#{__dir__}/find_replace/footnote_scope"
+    autoload :EndnoteScope, "#{__dir__}/find_replace/endnote_scope"
+    autoload :CommentScope, "#{__dir__}/find_replace/comment_scope"
+    autoload :StylesScope, "#{__dir__}/find_replace/styles_scope"
+    autoload :ParagraphWalker, "#{__dir__}/find_replace/paragraph_walker"
+    autoload :Result, "#{__dir__}/find_replace/result"
+  end
+end

data/lib/uniword/infrastructure/zip_packager.rb

@@ -44,15 +44,19 @@ module Uniword
         # causing put_next_entry to discard our Entry and create a fresh one.
         temp_path = "#{output_path}.#{Process.pid}.tmp"
 
+        ordered_content = order_content(content)
+        fixed_time = deterministic_timestamp
+
         was_zip64 = Zip.write_zip64_support
         Zip.write_zip64_support = false
         begin
           Zip::OutputStream.open(temp_path) do |zos|
-            content.each do |entry_path, entry_content|
+            ordered_content.each do |entry_path, entry_content|
               entry = Zip::Entry.new(temp_path, entry_path.to_s)
               entry.internal_file_attributes = 0
               entry.external_file_attributes = 0
               entry.fstype = Zip::FSTYPE_FAT
+              entry.time = fixed_time if fixed_time
 
               zos.put_next_entry(entry)
 
@@ -145,6 +149,29 @@ module Uniword
 
       private
 
+      # When `Uniword.configuration.deterministic_output` is true,
+      # reorder entries (priority for OPC-required first, alphabetical
+      # for the rest). Otherwise return content unchanged (insertion
+      # order, which matches Word's behavior).
+      #
+      # @param content [Hash<String, String>]
+      # @return [Hash<String, String>] ordered hash
+      def order_content(content)
+        return content unless Uniword.configuration.deterministic_output
+
+        ordered_keys = Docx::DeterministicOutput.reorder_entries(content.keys)
+        ordered_keys.to_h { |k| [k, content[k]] }
+      end
+
+      # Fixed timestamp for deterministic mode; nil otherwise.
+      #
+      # @return [Time, nil]
+      def deterministic_timestamp
+        return nil unless Uniword.configuration.deterministic_output
+
+        Docx::DeterministicOutput::FIXED_TIMESTAMP
+      end
+
       # Write content to a ZIP file using a temp file and atomic move.
       # This avoids Windows file locking issues by ensuring we never
       # write directly to the target file while it might be open.