uniword 1.5.0 → 1.5.2

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)
 
@@ -73,7 +77,7 @@ module Uniword
 
         move_temp_to_output(temp_path, output_path)
       ensure
-        FileUtils.rm_f(temp_path) if defined?(temp_path) && temp_path && File.exist?(temp_path)
+        remove_temp_file(temp_path)
       end
 
       # Add a file to an existing ZIP archive.
@@ -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.
@@ -184,7 +211,7 @@ module Uniword
 
         move_temp_to_output(temp_path, output_path)
       ensure
-        FileUtils.rm_f(temp_path) if defined?(temp_path) && temp_path && File.exist?(temp_path)
+        remove_temp_file(temp_path)
       end
 
       def move_temp_to_output(temp_path, output_path)
@@ -203,6 +230,25 @@ module Uniword
         end
       end
 
+      # Best-effort temp file removal with Windows-safe retries. AV
+      # scanners and the indexer briefly hold newly-written files; a
+      # single `FileUtils.rm_f` can return EACCES and leak the temp.
+      def remove_temp_file(temp_path)
+        return unless defined?(temp_path) && temp_path
+        return unless File.exist?(temp_path)
+
+        retries = 5
+        begin
+          FileUtils.rm_f(temp_path)
+        rescue Errno::EACCES
+          retries -= 1
+          if retries.positive?
+            sleep(0.3)
+            retry
+          end
+        end
+      end
+
       # Validate the content hash.
       #
       # @param content [Object] The content to validate

data/lib/uniword/lint/builtin_rules/banned_words.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Uniword
+  module Lint
+    module BuiltinRules
+      # Rule: paragraphs containing banned words trigger a finding.
+      class BannedWords < Rule
+        register :banned_words, self
+
+        # @param words [Array<String>] words to flag
+        def initialize(words:, **rest)
+          super(**rest)
+          @banned = Set.new(Array(words).map(&:downcase))
+        end
+
+        def check(document)
+          document.paragraphs.each_with_index do |paragraph, idx|
+            text = paragraph.text.to_s.downcase
+            @banned.each do |word|
+              next unless text.match?(/\b#{Regexp.escape(word)}\b/)
+
+              yield finding(
+                message: "Paragraph #{idx + 1} contains banned word " \
+                         "'#{word}'",
+                path: "paragraph[#{idx}]",
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/lint/builtin_rules/max_paragraph_length.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Lint
+    module BuiltinRules
+      # Rule: paragraphs longer than `max` words trigger a finding.
+      class MaxParagraphLength < Rule
+        register :max_paragraph_length, self
+
+        # @param max [Integer] word count threshold (default 200)
+        def initialize(max: 200, **rest)
+          super(**rest)
+          @max = max
+        end
+
+        def check(document)
+          document.paragraphs.each_with_index do |paragraph, idx|
+            text = paragraph.text.to_s
+            word_count = text.split.length
+            next if word_count <= @max
+
+            yield finding(
+              message: "Paragraph #{idx + 1} has #{word_count} words " \
+                       "(max #{@max})",
+              path: "paragraph[#{idx}]",
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/lint/builtin_rules/require_body.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Lint
+    module BuiltinRules
+      # Rule: documents must have a non-empty body.
+      class RequireBody < Rule
+        register :require_body, self
+
+        def check(document)
+          body = document.body
+          paragraphs = body&.paragraphs || []
+          return if paragraphs.any?
+
+          yield finding(
+            message: "Document body is empty",
+            path: "word/document.xml",
+          )
+        end
+      end
+    end
+  end
+end

data/lib/uniword/lint/builtin_rules/required_style.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Lint
+    module BuiltinRules
+      # Rule: required style presence. Triggers when the named style
+      # is missing from the document.
+      class RequiredStyle < Rule
+        register :required_style, self
+
+        # @param style_id [String, Array<String>] required styleId(s)
+        def initialize(style_id:, **rest)
+          super(**rest)
+          @required = Array(style_id)
+        end
+
+        def check(document)
+          present = document.styles_configuration&.styles&.map(&:styleId) || []
+          @required.each do |id|
+            next if present.include?(id)
+
+            yield finding(
+              message: "Required style '#{id}' is missing",
+              path: "styles.xml",
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/lint/builtin_rules.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Lint
+    # Container module for builtin rule classes. Loaded eagerly by
+    # `Lint` so each class's `register` call fires.
+    module BuiltinRules
+      autoload :MaxParagraphLength,
+               "#{__dir__}/builtin_rules/max_paragraph_length"
+      autoload :BannedWords, "#{__dir__}/builtin_rules/banned_words"
+      autoload :RequiredStyle, "#{__dir__}/builtin_rules/required_style"
+      autoload :RequireBody, "#{__dir__}/builtin_rules/require_body"
+
+      # Touch every autoload to force-load + register each rule.
+      ALL = [
+        MaxParagraphLength,
+        BannedWords,
+        RequiredStyle,
+        RequireBody,
+      ].freeze
+    end
+  end
+end

data/lib/uniword/lint/engine.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Lint
+    # Walks the document with each rule and aggregates findings.
+    class Engine
+      # @param document [Wordprocessingml::DocumentRoot]
+      # @param ruleset [Ruleset, Array<Rule>] rules to apply
+      def initialize(document:, ruleset:)
+        @document = document
+        @ruleset = wrap_ruleset(ruleset)
+      end
+
+      # @return [Result]
+      def run
+        result = Result.new
+        @ruleset.rules.each do |rule|
+          rule.check(@document) { |finding| result.add(finding) }
+        end
+        result
+      end
+
+      private
+
+      def wrap_ruleset(ruleset)
+        return ruleset if ruleset.is_a?(Ruleset)
+
+        Ruleset.new(Array(ruleset))
+      end
+    end
+  end
+end

data/lib/uniword/lint/result.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Lint
+    # Aggregated lint result with severity counts.
+    class Result
+      SEVERITY_ORDER = %i[error warning info].freeze
+
+      attr_reader :findings
+
+      def initialize
+        @findings = []
+      end
+
+      # @param finding [Hash]
+      # @return [void]
+      def add(finding)
+        @findings << finding
+      end
+
+      # True when at least one :error severity finding exists.
+      #
+      # @return [Boolean]
+      def errors?
+        @findings.any? { |f| f[:severity] == :error }
+      end
+
+      # Count by severity.
+      #
+      # @return [Hash{Symbol => Integer}]
+      def by_severity
+        @findings.group_by { |f| f[:severity] }
+          .transform_values(&:count)
+      end
+
+      # Count by rule name.
+      #
+      # @return [Hash{Symbol => Integer}]
+      def by_rule
+        @findings.group_by { |f| f[:rule] }
+          .transform_values(&:count)
+      end
+
+      # Total finding count.
+      #
+      # @return [Integer]
+      def count
+        @findings.length
+      end
+
+      # True when zero findings.
+      #
+      # @return [Boolean]
+      def empty?
+        @findings.empty?
+      end
+    end
+  end
+end