uniword 1.7.1 → 1.7.2

data/lib/uniword/diff/lcs.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Diff
+    # Longest-common-subsequence alignment over sequences.
+    #
+    # Shared substrate for the differ (paragraph alignment) and the
+    # redliner (paragraph and word-token alignment). Sequences are
+    # compared by element equality, so both operate on plain strings.
+    module Lcs
+      # Matched (old_index, new_index) pairs, ascending.
+      #
+      # @param old_seq [Array] base sequence
+      # @param new_seq [Array] revised sequence
+      # @return [Array<Array(Integer, Integer)>]
+      def self.pairs(old_seq, new_seq)
+        m = old_seq.size
+        n = new_seq.size
+
+        dp = Array.new(m + 1) { Array.new(n + 1, 0) }
+        (1..m).each do |i|
+          (1..n).each do |j|
+            dp[i][j] = if old_seq[i - 1] == new_seq[j - 1]
+                         dp[i - 1][j - 1] + 1
+                       else
+                         [dp[i - 1][j], dp[i][j - 1]].max
+                       end
+          end
+        end
+
+        matches = []
+        i = m
+        j = n
+        while i.positive? && j.positive?
+          if old_seq[i - 1] == new_seq[j - 1]
+            matches << [i - 1, j - 1]
+            i -= 1
+            j -= 1
+          elsif dp[i - 1][j] >= dp[i][j - 1]
+            i -= 1
+          else
+            j -= 1
+          end
+        end
+
+        matches.reverse
+      end
+
+      # Alignment walk over two sequences.
+      #
+      # Returns tuples [action, old_index, new_index] in document
+      # order, where action is :kept or :modified (both indexes set),
+      # :removed (old only), or :added (new only).
+      #
+      # @param old_seq [Array]
+      # @param new_seq [Array]
+      # @return [Array<Array(Symbol, Integer, Integer)>]
+      def self.alignment(old_seq, new_seq)
+        lcs = pairs(old_seq, new_seq)
+
+        result = []
+        old_i = 0
+        new_i = 0
+        lcs_idx = 0
+
+        while old_i < old_seq.size || new_i < new_seq.size
+          old_in_lcs = lcs_idx < lcs.size &&
+            lcs[lcs_idx][0] == old_i
+          new_in_lcs = lcs_idx < lcs.size &&
+            lcs[lcs_idx][1] == new_i
+
+          if old_in_lcs && new_in_lcs
+            action = old_seq[old_i] == new_seq[new_i] ? :kept : :modified
+            result << [action, old_i, new_i]
+            old_i += 1
+            new_i += 1
+            lcs_idx += 1
+          elsif old_in_lcs
+            result << [:added, nil, new_i]
+            new_i += 1
+          elsif new_in_lcs
+            result << [:removed, old_i, nil]
+            old_i += 1
+          elsif old_i < old_seq.size && new_i < new_seq.size
+            result << [:modified, old_i, new_i]
+            old_i += 1
+            new_i += 1
+          elsif old_i < old_seq.size
+            result << [:removed, old_i, nil]
+            old_i += 1
+          else
+            result << [:added, nil, new_i]
+            new_i += 1
+          end
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/uniword/diff/redline_result.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Uniword
+  module Diff
+    # Value object holding the result of redlining two documents.
+    #
+    # Carries the redlined base document plus change statistics.
+    #
+    # @example
+    #   result = Redliner.new(base_doc, revised_doc).redline
+    #   result.document.save("redline.docx")
+    #   puts result.summary
+    class RedlineResult
+      attr_reader :document, :stats
+
+      # @param document [Wordprocessingml::DocumentRoot] redlined base
+      # @param stats [Hash{Symbol => Integer}] change counts by kind
+      #   (:kept, :modified, :added, :removed paragraphs)
+      def initialize(document:, stats: {})
+        @document = document
+        @stats = stats
+      end
+
+      # Number of tracked insertion wrappers (w:ins) emitted.
+      #
+      # @return [Integer]
+      def insertions
+        document.body.paragraphs.sum { |p| p.insertions.size }
+      end
+
+      # Number of tracked deletion wrappers (w:del) emitted.
+      #
+      # @return [Integer]
+      def deletions
+        document.body.paragraphs.sum { |p| p.deletions.size }
+      end
+
+      # Whether the redline carries no tracked changes.
+      #
+      # @return [Boolean]
+      def empty?
+        insertions.zero? && deletions.zero? &&
+          stats[:added].to_i.zero? && stats[:removed].to_i.zero? &&
+          stats[:modified].to_i.zero?
+      end
+
+      # Human-readable summary of the redline.
+      #
+      # @return [String]
+      def summary
+        return "No differences found." if empty?
+
+        parts = []
+        if stats[:added].positive?
+          parts << "#{stats[:added]} paragraph(s) inserted"
+        end
+        if stats[:removed].positive?
+          parts << "#{stats[:removed]} paragraph(s) deleted"
+        end
+        if stats[:modified].positive?
+          parts << "#{stats[:modified]} paragraph(s) modified"
+        end
+        parts << "#{insertions} insertion(s), #{deletions} deletion(s)"
+        parts.join(", ")
+      end
+
+      # Serialize to a JSON string.
+      #
+      # @return [String] Pretty-printed JSON
+      def to_json(*_args)
+        JSON.pretty_generate(to_h)
+      end
+
+      # Convert to a plain Hash suitable for serialization.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          paragraphs: {
+            kept: stats[:kept].to_i,
+            modified: stats[:modified].to_i,
+            added: stats[:added].to_i,
+            removed: stats[:removed].to_i,
+          },
+          insertions: insertions,
+          deletions: deletions,
+          summary: summary,
+        }
+      end
+    end
+  end
+end

data/lib/uniword/diff/redliner.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Diff
+    # Produces a tracked-changes (redline) document from two revisions.
+    #
+    # The base document (the old revision) is rewritten in place: a
+    # paragraph removed in the new revision has its runs wrapped in
+    # w:del and its paragraph mark marked deleted; an added paragraph
+    # is inserted with its runs wrapped in w:ins and its paragraph
+    # mark marked inserted; a modified paragraph keeps the base text
+    # with the word-level delta emitted as interleaved w:del / w:ins
+    # runs. Tables pass through unchanged (issue #77 scope item 3).
+    #
+    # Revision identity (w:id, author, date) is deterministic per
+    # change position, so the same pair of documents always produces
+    # the same redline.
+    #
+    # @example
+    #   base = DocumentFactory.from_file("old.docx")
+    #   revised = DocumentFactory.from_file("new.docx")
+    #   result = Redliner.new(base, revised, author: "Alice").redline
+    #   result.document.save("redline.docx")
+    class Redliner
+      include Builder::DeterministicId
+
+      DEFAULT_AUTHOR = "uniword"
+
+      # Tokenizer: words and whitespace runs, originals preserved so
+      # concatenation reproduces the paragraph text exactly.
+      TOKEN_PATTERN = /\S+|\s+/
+
+      # Wordprocessingml::Paragraph children the redliner does not
+      # rebuild; their element_order entries are carried over on
+      # rewritten paragraphs.
+      REBUILT_CHILDREN = %w[pPr r ins del].freeze
+
+      # @param old_doc [Wordprocessingml::DocumentRoot] base revision,
+      #   rewritten in place into the redline
+      # @param new_doc [Wordprocessingml::DocumentRoot] revised version
+      # @param author [String] revision author for emitted changes
+      # @param date [String, nil] revision date (ISO 8601) for emitted
+      #   changes; omitted from the XML when nil
+      def initialize(old_doc, new_doc, author: DEFAULT_AUTHOR, date: nil)
+        @old_doc = old_doc
+        @new_doc = new_doc
+        @author = author
+        @date = date
+        @inserted = 0
+        @old_cursor = 0
+        @seq = 0
+        @stats = Hash.new(0)
+      end
+
+      # Rewrite the base document into a redline.
+      #
+      # @return [RedlineResult] the redlined document plus change stats
+      def redline
+        Lcs.alignment(old_texts, new_texts).each { |step| apply(step) }
+        RedlineResult.new(document: @old_doc, stats: @stats)
+      end
+
+      private
+
+      def body
+        @old_doc.body
+      end
+
+      def old_paras
+        body.paragraphs
+      end
+
+      def new_paras
+        @new_doc.body&.paragraphs || []
+      end
+
+      def old_texts
+        old_paras.map { |p| p.text.to_s }
+      end
+
+      def new_texts
+        new_paras.map { |p| p.text.to_s }
+      end
+
+      def apply((action, old_i, new_i))
+        case action
+        when :kept
+          @stats[:kept] += 1
+          @old_cursor += 1
+        when :modified
+          if old_paras[old_i].text == new_paras[new_i].text
+            @stats[:kept] += 1
+          else
+            rewrite_modified(old_paras[old_i], new_paras[new_i])
+            @stats[:modified] += 1
+          end
+          @old_cursor += 1
+        when :removed
+          mark_deleted(old_paras[old_i])
+          @stats[:removed] += 1
+          @old_cursor += 1
+        when :added
+          insert_added(new_paras[new_i])
+          @stats[:added] += 1
+        end
+      end
+
+      # Word-level delta of two paragraphs as ordered segments.
+      #
+      # Contiguous tokens from the same source run merge into one
+      # segment, so a single-span change yields exactly one revision
+      # element, the way Word writes redlines.
+      #
+      # @return [Array<Hash>] { kind: :keep/:del/:ins, text:, properties: }
+      def diff_segments(old_para, new_para)
+        old_tokens = tokenize(old_para)
+        new_tokens = tokenize(new_para)
+
+        segments = []
+        current = nil
+        Lcs.alignment(old_tokens.map(&:last), new_tokens.map(&:last))
+          .each do |action, old_i, new_i|
+          case action
+          when :kept
+            current = merge(segments, current, :keep,
+                            old_tokens[old_i].last,
+                            old_tokens[old_i].first.properties)
+          when :removed, :modified
+            current = merge(segments, current, :del,
+                            old_tokens[old_i].last,
+                            old_tokens[old_i].first.properties)
+          end
+          next unless %i[added modified].include?(action)
+
+          current = merge(segments, current, :ins,
+                          new_tokens[new_i].last,
+                          new_tokens[new_i].first.properties)
+        end
+        merge(segments, current, nil, nil, nil)
+        segments.reject { |segment| segment[:text].empty? }
+      end
+
+      # Append a token to the current segment, or start a new one when
+      # the kind or the owning run's properties change.
+      def merge(segments, current, kind, text, properties)
+        if current && current[:kind] == kind &&
+            current[:properties].equal?(properties)
+          current[:text] << text
+          return current
+        end
+
+        segments << current if current
+        segment = { kind: kind, text: +"", properties: properties }
+        segment[:text] << text if text
+        segment
+      end
+
+      # Tokens of a paragraph as [run, text] pairs.
+      def tokenize(para)
+        para.runs.flat_map do |run|
+          run.text_string.to_s.scan(TOKEN_PATTERN).map { |t| [run, t] }
+        end
+      end
+
+      def rewrite_modified(old_para, new_para)
+        kept_runs = []
+        deletions = []
+        insertions = []
+        names = []
+        names << "pPr" if old_para.properties
+
+        diff_segments(old_para, new_para).each do |segment|
+          case segment[:kind]
+          when :keep
+            kept_runs << Wordprocessingml::Run.new(
+              properties: segment[:properties], text: segment[:text],
+            )
+            names << "r"
+          when :del
+            deletions << Wordprocessingml::Deletion.new(
+              id: next_id, author: @author, date: @date,
+              runs: [Wordprocessingml::Run.new(
+                properties: segment[:properties],
+                del_text: deleted_text(segment[:text]),
+              )]
+            )
+            names << "del"
+          when :ins
+            insertions << Wordprocessingml::Insertion.new(
+              id: next_id, author: @author, date: @date,
+              runs: [Wordprocessingml::Run.new(
+                properties: segment[:properties], text: segment[:text],
+              )]
+            )
+            names << "ins"
+          end
+        end
+
+        old_para.runs = kept_runs
+        old_para.deletions = deletions
+        old_para.insertions = insertions
+        set_paragraph_order(old_para, names)
+      end
+
+      # Wrap every run of a removed paragraph in w:del and mark the
+      # paragraph mark deleted, so accepting the revision drops the
+      # whole paragraph.
+      def mark_deleted(para)
+        deleted_runs = para.runs.map { |run| deleted_run(run) }
+        para.runs = []
+
+        names = []
+        names << "pPr" if para.properties
+        unless deleted_runs.empty?
+          para.deletions = [Wordprocessingml::Deletion.new(
+            id: next_id, author: @author, date: @date, runs: deleted_runs,
+          )]
+          names << "del"
+        end
+
+        props = ensure_mark(para)
+        props.run_properties ||= Wordprocessingml::RunProperties.new
+        props.run_properties.del =
+          Wordprocessingml::DeletedParagraphMark.new(
+            id: next_id, author: @author, date: @date,
+          )
+        set_paragraph_order(para, names)
+      end
+
+      def deleted_text(text)
+        deleted = Wordprocessingml::DeletedText.new(content: text)
+        if Wordprocessingml::Text.preserve_whitespace?(text)
+          deleted.xml_space = "preserve"
+        end
+        deleted
+      end
+
+      def deleted_run(run)
+        text = run.text_string.to_s
+        return run if text.empty?
+
+        Wordprocessingml::Run.new(properties: run.properties,
+                                  del_text: deleted_text(text))
+      end
+
+      # Insert a new-only paragraph with its runs wrapped in w:ins and
+      # its paragraph mark marked inserted, right before the base
+      # paragraph the alignment cursor sits on.
+      def insert_added(new_para)
+        para = Wordprocessingml::Paragraph.new
+        para.properties =
+          new_para.properties || Wordprocessingml::ParagraphProperties.new
+        para.properties.run_properties ||= Wordprocessingml::RunProperties.new
+        para.properties.run_properties.ins =
+          Wordprocessingml::InsertedParagraphMark.new(
+            id: next_id, author: @author, date: @date,
+          )
+
+        names = ["pPr"]
+        if new_para.runs.any?
+          para.insertions = [Wordprocessingml::Insertion.new(
+            id: next_id, author: @author, date: @date,
+            runs: new_para.runs.dup
+          )]
+          names << "ins"
+        end
+        set_paragraph_order(para, names)
+
+        position = @old_cursor + @inserted
+        body.paragraphs.insert(position, para)
+        insert_order_entry(position)
+        @inserted += 1
+      end
+
+      # Record the paragraph's child sequence in element_order so the
+      # interleaved runs / del / ins serialize in emission order and
+      # untouched children (hyperlinks, bookmarks, comments) survive.
+      def set_paragraph_order(para, names)
+        order = para.element_order
+        carried = if order.nil? || order.empty?
+                    []
+                  else
+                    order.map(&:name).reject do |name|
+                      REBUILT_CHILDREN.include?(name)
+                    end
+                  end
+        para.element_order = (names + carried).map do |name|
+          Lutaml::Xml::Element.new("Element", name)
+        end
+      end
+
+      # Insert the element_order entry for a body paragraph added at
+      # +paragraph_index+ so it serializes at its document position.
+      def insert_order_entry(paragraph_index)
+        order = body.element_order
+        return if order.nil? || order.empty?
+
+        order = Ooxml::ElementOrder.mutable_order(body)
+        p_positions = order.each_index.select { |i| order[i].name == "p" }
+        at = if paragraph_index < p_positions.size
+               p_positions[paragraph_index]
+             else
+               order.index { |e| e.name == "sectPr" } || order.size
+             end
+        order.insert(at, Lutaml::Xml::Element.new("Element", "p"))
+      end
+
+      def ensure_mark(para)
+        para.properties ||= Wordprocessingml::ParagraphProperties.new
+        para.properties
+      end
+
+      def next_id
+        @seq += 1
+        deterministic_id("uniword-redline", @seq).to_s
+      end
+    end
+  end
+end

data/lib/uniword/diff.rb

@@ -13,7 +13,10 @@ module Uniword
     autoload :DiffResult, "uniword/diff/diff_result"
     autoload :DocumentDiffer, "uniword/diff/document_differ"
     autoload :Formatter, "uniword/diff/formatter"
+    autoload :Lcs, "uniword/diff/lcs"
     autoload :PackageDiffer, "uniword/diff/package_differ"
+    autoload :Redliner, "uniword/diff/redliner"
+    autoload :RedlineResult, "uniword/diff/redline_result"
     autoload :XmlChange, "uniword/diff/package_diff_result"
     autoload :ZipMetadataChange, "uniword/diff/package_diff_result"
     autoload :OpcIssue, "uniword/diff/package_diff_result"

data/lib/uniword/errors.rb

@@ -144,4 +144,37 @@ module Uniword
     # @return [String] The reason
     attr_reader :reason
   end
+
+  # Raised when a template fill (strict mode) finds placeholders whose
+  # variables have no data
+  class MissingVariablesError < Error
+    # @param variables [Array<String>] The variable names without data
+    def initialize(variables)
+      super("Missing template variables: #{variables.join(', ')}")
+      @variables = variables
+    end
+
+    # @return [Array<String>] The missing variable names
+    attr_reader :variables
+  end
+
+  # Raised when a strict plain-text conversion (Converter::PlainText)
+  # encounters features that would be dropped or degraded in the
+  # target format
+  class FidelityError < Error
+    # @param format [Symbol, String] The target format of the conversion
+    # @param dropped_features [Array<String>] The features that would be lost
+    def initialize(format, dropped_features)
+      super("Strict #{format} conversion would drop: " \
+            "#{dropped_features.join(', ')}")
+      @format = format
+      @dropped_features = dropped_features
+    end
+
+    # @return [Symbol, String] The target format
+    attr_reader :format
+
+    # @return [Array<String>] The features that would be lost
+    attr_reader :dropped_features
+  end
 end

data/lib/uniword/mhtml/word_css.rb

@@ -119,29 +119,37 @@ module Uniword
 
       # Build a CSS rule for a style.
       #
-      # @param style [Style] The style
+      # @param style [Wordprocessingml::Style] The style
       # @return [String, nil] The CSS rule or nil
       def self.build_style_rule(style)
         return nil unless style
 
+        # w:styleId is optional in the schema, and without it there is no
+        # class selector to hang the rule on.
+        style_id = style.id
+        return nil if style_id.nil? || style_id.empty?
+
         properties = []
 
         # Font properties
-        properties << "font-family: '#{style.font}'" if style.font
+        font_family = style.font_family
+        properties << "font-family: '#{font_family}'" if font_family
         if style.font_size
-          properties << "font-size: #{CssNumberFormatter.format(style.font_size, 'pt',
-                                                                precision: 1)}"
+          # w:sz is in half-points, so it needs the font-size formatter.
+          formatted_size = CssNumberFormatter
+            .format_font_size(style.font_size, precision: 1)
+          properties << "font-size: #{formatted_size}"
         end
         properties << "font-weight: bold" if style.bold
         properties << "font-style: italic" if style.italic
 
-        # Paragraph properties
-        properties << "text-align: #{style.alignment}" if style.alignment
+        # Paragraph properties, whose alignment is a w:jc wrapper element
+        alignment = style.alignment&.value
+        properties << "text-align: #{alignment}" if alignment
 
         return nil if properties.empty?
 
-        selector = ".#{style.style_id}"
-        "#{selector} {\n  #{properties.join(";\n  ")};\n}"
+        ".#{style_id} {\n  #{properties.join(";\n  ")};\n}"
       end
 
       # Build a CSS rule for list numbering.

data/lib/uniword/ooxml/types/ooxml_boolean.rb

@@ -11,8 +11,9 @@ module Uniword
       #
       # Parsing: "1"/"true"/"on" -> true, "0"/"false"/"off"/nil -> false
       # Serialization: true -> "1", false -> "0"
-      # Anything else raises Lutaml::Model::Type::InvalidValueError
-      # instead of passing through unchanged.
+      # Serializing anything else raises
+      # Lutaml::Model::Type::InvalidValueError, because a value the program
+      # set is a bug rather than a document we were handed.
       class OoxmlBoolean < Lutaml::Model::Type::Boolean
         # Accepted ST_OnOff spellings for Boolean true
         TRUE_VALUES = [true, 1, "1", "true", "on"].freeze
@@ -23,14 +24,25 @@ module Uniword
         # All accepted ST_OnOff spellings
         ON_OFF_VALUES = (TRUE_VALUES + FALSE_VALUES).freeze
 
+        # The one ST_OnOff reading, shared by these attribute types and by
+        # Properties::BooleanElement.
+        #
+        # A reader must not raise on a malformed document. One bad token in
+        # styles.xml used to kill the whole parse, and a token outside the
+        # vocabulary is not an off token, so it reads as on — the same way an
+        # unrecognised w:val does.
+        #
+        # @param value [Object] Raw ST_OnOff token
+        # @return [Boolean] true when the toggle is on
+        def self.on?(value)
+          !FALSE_VALUES.include?(value)
+        end
+
         def self.cast(value, _options = {})
           return value if Lutaml::Model::Utils.uninitialized?(value)
-          return true if TRUE_VALUES.include?(value)
-          return false if FALSE_VALUES.include?(value) || value.nil?
+          return false if value.nil?
 
-          raise Lutaml::Model::Type::InvalidValueError.new(
-            value, ON_OFF_VALUES
-          )
+          on?(value)
         end
 
         def self.serialize(value)

data/lib/uniword/ooxml/types/ooxml_boolean_optional.rb

@@ -10,9 +10,9 @@ module Uniword
       # Key behavior:
       # - cast(nil) -> nil (doesn't convert to false like OoxmlBoolean)
       # - cast("1"/"true"/"on") -> true, cast("0"/"false"/"off") -> false
-      # - cast of any other value raises
-      #   Lutaml::Model::Type::InvalidValueError instead of passing
-      #   through unchanged
+      # - cast of any other token -> true, the same reading
+      #   Properties::BooleanElement gives an unrecognised w:val. A reader
+      #   must not raise on a malformed document.
       # - to_xml(true) -> "1"
       # - to_xml(false) -> "0" (explicit false in original)
       # - to_xml(nil) -> nil (attribute absent, omit from output)
@@ -26,12 +26,8 @@ module Uniword
         def self.cast(value, _options = {})
           return value if Lutaml::Model::Utils.uninitialized?(value)
           return nil if value.nil?
-          return true if OoxmlBoolean::TRUE_VALUES.include?(value)
-          return false if OoxmlBoolean::FALSE_VALUES.include?(value)
 
-          raise Lutaml::Model::Type::InvalidValueError.new(
-            value, OoxmlBoolean::ON_OFF_VALUES
-          )
+          OoxmlBoolean.on?(value)
         end
 
         def self.serialize(value)