uniword 1.5.1 → 1.5.3

data/lib/uniword/cli/main.rb

@@ -383,6 +383,92 @@ module Uniword
       say "Uniword version #{Uniword::VERSION}", :green
     end
 
+    desc "redact INPUT OUTPUT", "Redact PII patterns from a document"
+    long_desc <<~DESC
+      Replace PII patterns (SSN, email, phone, credit card, IPv4)
+      with [REDACTED] across the document. Compliance use case Word
+      cannot serve.
+
+      Scopes: body, headers, footers, footnotes, endnotes, comments,
+      styles, all (default). Pass --scope multiple times to combine.
+
+      Examples:
+        $ uniword redact report.docx redacted.docx
+        $ uniword redact report.docx redacted.docx --pattern ssn --pattern email
+        $ uniword redact report.docx redacted.docx --scope body --verbose
+    DESC
+    option :pattern, type: :array, default: [:pii],
+                     desc: "Pattern(s): pii (default), ssn, email, " \
+                           "phone, credit_card, ipv4"
+    option :scope, type: :array, default: [:all],
+                   desc: "Scope(s): body, headers, footers, footnotes, " \
+                         "endnotes, comments, styles, all"
+    option :verbose, aliases: "-v", type: :boolean, default: false,
+                     desc: "Show per-pattern counts"
+    def redact(input_path, output_path)
+      doc = load_document(input_path)
+      patterns = resolve_redact_patterns(options[:pattern])
+      result = doc.redact(patterns: patterns,
+                          scope: expand_scopes(options[:scope]))
+
+      if options[:verbose]
+        say "Redactions by pattern:", :cyan
+        result.by_pattern.each do |name, count|
+          say "  #{name}: #{count}" if count.positive?
+        end
+      end
+      say "Redacted #{result.count} match(es) in #{output_path}", :green
+      doc.save(output_path)
+    rescue Uniword::Error => e
+      handle_error(e)
+    rescue StandardError => e
+      handle_error(e, verbose: options[:verbose])
+    end
+
+    desc "find-replace INPUT OUTPUT PATTERN REPLACEMENT",
+         "Find and replace text across document parts"
+    long_desc <<~DESC
+      Replace every non-overlapping match of PATTERN with REPLACEMENT
+      across the configured document parts -- Word's Home → Replace
+      dialog as a one-shot CLI command.
+
+      Scopes: body, headers, footers, footnotes, endnotes, comments,
+      styles, all (default). Pass --scope multiple times to combine.
+
+      Examples:
+        $ uniword find-replace report.docx out.docx "Acme" "MegaCorp"
+        $ uniword find-replace report.docx out.docx 'Chapter (\\d+)' 'Ch. \\1' --regex
+        $ uniword find-replace report.docx out.docx "DRAFT" "FINAL" --scope headers --scope footers
+        $ uniword find-replace report.docx out.docx "foo" "bar" --ignore-case --verbose
+    DESC
+    option :scope, type: :array, default: [:all],
+                   desc: "Scope(s): body, headers, footers, footnotes, " \
+                         "endnotes, comments, styles, all"
+    option :regex, type: :boolean, default: false,
+                   desc: "Treat PATTERN as a regular expression"
+    option :ignore_case, type: :boolean, default: false,
+                         desc: "Case-insensitive match (plain-string mode)"
+    option :verbose, aliases: "-v", type: :boolean, default: false,
+                     desc: "Show per-scope counts"
+    def find_replace(input_path, output_path, pattern, replacement)
+      scopes = expand_scopes(options[:scope])
+      doc = load_document(input_path)
+      result = run_find_replace(doc, pattern, replacement, scopes)
+
+      if options[:verbose]
+        say "Replacements by scope:", :cyan
+        result.by_scope.each do |scope_name, count|
+          say "  #{scope_name}: #{count}" if count.positive?
+        end
+      end
+      say "Replaced #{result.count} match(es) in #{output_path}", :green
+      doc.save(output_path)
+    rescue Uniword::Error => e
+      handle_error(e)
+    rescue StandardError => e
+      handle_error(e, verbose: options[:verbose])
+    end
+
     # Register subcommands
     desc "theme SUBCOMMAND", "Manage document themes"
     subcommand "theme", ThemeCLI
@@ -439,6 +525,54 @@ module Uniword
 
     private
 
+    # -- find-replace helpers -------------------------------------------
+
+    # Normalize --scope arguments. `[:all]` collapses to `:all`; any
+    # combination of named scopes stays as an array.
+    #
+    # @param scopes [Array<Symbol>]
+    # @return [Symbol, Array<Symbol>]
+    def expand_scopes(scopes)
+      return :all if scopes.nil? || scopes.empty?
+
+      symbols = scopes.map(&:to_sym)
+      return :all if symbols.include?(:all)
+
+      symbols
+    end
+
+    # Build the right matcher from --regex flag and run the engine.
+    def run_find_replace(doc, pattern, replacement, scopes)
+      matcher = build_find_replace_matcher(pattern, replacement)
+      Uniword::FindReplace::Engine.new(document: doc, matcher: matcher,
+                                       scopes: scopes).run
+    end
+
+    # Translate --pattern args (`pii`, `ssn`, ...) into a list of
+    # Redact::Pattern objects via PatternLibrary.
+    #
+    # @param names [Array<Symbol>]
+    # @return [Array<Uniword::Redact::Pattern>]
+    def resolve_redact_patterns(names)
+      symbols = Array(names).map(&:to_sym)
+      return :pii if symbols == [:pii]
+
+      Uniword::Redact::PatternLibrary.select(symbols)
+    end
+
+    def build_find_replace_matcher(pattern, replacement)
+      if options[:regex]
+        Uniword::FindReplace::RegexMatcher.new(pattern: pattern,
+                                               replacement: replacement)
+      else
+        Uniword::FindReplace::StringMatcher.new(
+          pattern: pattern,
+          replacement: replacement,
+          ignore_case: options[:ignore_case],
+        )
+      end
+    end
+
     # Report substantive repairs; routine normalization is summarized
     # separately so a healthy document does not look "repaired".
     def report_repairs(fixes)

data/lib/uniword/cli/review_cli.rb

@@ -212,6 +212,40 @@ module Uniword
       handle_error(e)
     end
 
+    desc "track-changes SUBCOMMAND", "Toggle or query change tracking"
+    long_desc <<~DESC
+      Turn Word's Review → Track Changes toggle on or off, or query
+      its current state.
+
+      Examples:
+        $ uniword review track-changes on input.docx output.docx
+        $ uniword review track-changes off input.docx output.docx
+        $ uniword review track-changes status input.docx
+    DESC
+    def track_changes(command, input_path, output_path = nil)
+      doc = load_document(input_path)
+
+      case command.to_sym
+      when :on
+        doc.track_changes_on!
+        doc.save(output_path || input_path)
+        say "Change tracking ON in #{output_path || input_path}", :green
+      when :off
+        doc.track_changes_off!
+        doc.save(output_path || input_path)
+        say "Change tracking OFF in #{output_path || input_path}", :green
+      when :status
+        say doc.track_changes_enabled? ? "ON" : "OFF"
+      else
+        say "Unknown subcommand: #{command}. Use on, off, or status.", :red
+        exit 1
+      end
+    rescue Uniword::Error => e
+      handle_error(e)
+    rescue StandardError => e
+      handle_error(e)
+    end
+
     desc "interactive FILE", "Interactively review all changes"
     long_desc <<~DESC
       Step through comments and tracked changes one-by-one.

data/lib/uniword/configuration.rb

@@ -52,6 +52,14 @@ module Uniword
     # @return [Symbol] `:strip` (default) or `:raise`
     attr_reader :on_noncompliant_content
 
+    # Whether save produces deterministic output (fixed ZIP
+    # timestamps, sorted entry order). Default false (Word-compatible
+    # timestamps and order). Enable for git-tracked documents where
+    # byte-stable diffs matter.
+    #
+    # @return [Boolean]
+    attr_reader :deterministic_output
+
     # Create a configuration with default policy values.
     #
     # Defaults: validate_on_save: true, xsd_validation: false,
@@ -68,6 +76,7 @@ module Uniword
       @xsd_validation = false
       @log_save_fixes = true
       @on_noncompliant_content = :strip
+      @deterministic_output = false
       self
     end
 
@@ -109,6 +118,14 @@ module Uniword
       @on_noncompliant_content = typed_mode(value, :on_noncompliant_content)
     end
 
+    # Set the deterministic-output policy.
+    #
+    # @param value [Boolean]
+    # @return [Boolean]
+    def deterministic_output=(value)
+      @deterministic_output = typed_boolean(value, :deterministic_output)
+    end
+
     private
 
     # Validate that a value is strictly boolean.

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

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/docx/deterministic_output.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    # Normalizes package output for byte-stable diffs.
+    #
+    # When `Uniword.configuration.deterministic_output` is true:
+    # - ZIP entry timestamps are fixed at 1980-01-01 (DOS epoch).
+    # - ZIP entry order is sorted alphabetically (except
+    #   `[Content_Types].xml` and `_rels/.rels`, which must come
+    #   first per OPC).
+    # - Compression level is fixed.
+    #
+    # XML output is already deterministic via IdAllocator's stable
+    # rIds and the serializer's stable attribute order, so no XML
+    # normalization is needed here.
+    module DeterministicOutput
+      # Fixed DOS epoch timestamp (1980-01-01 00:00:00 UTC) for ZIP
+      # entries. ZIP format doesn't support earlier dates.
+      FIXED_TIMESTAMP = Time.utc(1980, 1, 1, 0, 0, 0).freeze
+
+      # Reorder entries: [Content_Types].xml and _rels/.rels first
+      # (required by OPC), then alphabetical for the rest.
+      #
+      # @param entries [Array<String>] ZIP entry paths
+      # @return [Array<String>] reordered paths
+      def self.reorder_entries(entries)
+        priority = PRIORITY_ORDER.filter_map { |p| entries.find { |e| e == p } }
+        rest = (entries - PRIORITY_ORDER).sort
+        priority + rest
+      end
+
+      # Apply fixed timestamps to a ZIP output stream's entries.
+      #
+      # @param zos [Zip::OutputStream]
+      # @return [void]
+      def self.stamp_entries(zos)
+        zos.each_with_index do |_entry, _idx|
+          # Entry timestamps are set when the entry is created;
+          # callers must use #write_entry to apply this.
+        end
+      end
+
+      PRIORITY_ORDER = %w[[Content_Types].xml _rels/.rels].freeze
+    end
+  end
+end

data/lib/uniword/docx.rb

@@ -29,5 +29,6 @@ module Uniword
     autoload :Profile, "#{__dir__}/docx/profile"
     autoload :DocumentStatistics, "#{__dir__}/docx/document_statistics"
     autoload :Reconciler, "#{__dir__}/docx/reconciler"
+    autoload :DeterministicOutput, "#{__dir__}/docx/deterministic_output"
   end
 end

data/lib/uniword/find_replace/body_scope.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Uniword
+  module FindReplace
+    # Body scope: text in `word/document.xml`. Walks every paragraph
+    # reachable from the body (including paragraphs nested in table
+    # cells and structured document tags).
+    class BodyScope < Scope
+      # @return [Symbol]
+      def name
+        :body
+      end
+
+      # @yieldparam text_element [Wordprocessingml::Text]
+      # @yieldparam accessor [Scope::TextAccessor]
+      def each_text_node
+        return unless @document.body
+
+        each_text_in_containers([@document.body]) { |*a| yield(*a) }
+      end
+    end
+  end
+end