uniword 1.7.1 → 1.7.3

data/lib/uniword/converter/plain_text.rb

@@ -0,0 +1,425 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Converter
+    # Plain-text editing round trip for Word documents (issue #80).
+    #
+    # Bridges Uniword::Wordprocessingml::DocumentRoot to Markdown and
+    # AsciiDoc through Coradoc's hub-and-spoke CoreModel:
+    #
+    #   DocumentRoot -> Coradoc::Docx.parse_to_core -> core
+    #     -> (Coradoc::Markdown | Coradoc::AsciiDoc) writer
+    #
+    #   (Coradoc::Markdown | Coradoc::AsciiDoc) parser -> core
+    #     -> Coradoc::Docx.serialize -> DocumentRoot
+    #
+    # The coradoc gems are OPTIONAL runtime dependencies: they are
+    # required lazily inside the conversion methods, never at file
+    # load. When missing, a DependencyError with an install hint is
+    # raised.
+    #
+    # == Fidelity boundary
+    #
+    # Supported (round-tripped through the CoreModel):
+    # * headings h1-h6, paragraphs
+    # * bold / italic / underline / strikethrough runs
+    # * bulleted and numbered lists
+    # * tables with a header row
+    # * links (bridge resolves relationship ids to target URLs)
+    # * bookmarks (heading/paragraph anchor id propagation)
+    # * footnotes (coradoc-docx 0.1.6 carries them into the core
+    #   model; to md/adoc emits GFM [^id] + definitions)
+    #
+    # Dropped or degraded (recorded on PlainTextResult, warned about;
+    # +strict: true+ raises FidelityError):
+    # * headers/footers
+    # * section properties
+    # * comments
+    # * tracked changes (w:ins/w:del)
+    # * structured document tags (content survives, wrapper unwrapped)
+    # * math (OMML)
+    # * images (docx extractor does not carry drawings; coradoc#322)
+    #
+    # Never carried by any plain-text format (not detected per document):
+    # themes, settings, font table, and other package-level parts.
+    #
+    # From the plain-text side, links written to DOCX resolve to real
+    # External relationships on save. Upstream flattenings that remain:
+    # coradoc-markdown's CoreModel transform emits inline Markdown links
+    # as literal text, so from_markdown keeps links as text while
+    # from_asciidoc builds real hyperlinks (coradoc#320); the same
+    # inline parser gap leaves from_markdown footnote REFERENCES as
+    # literal text (definitions do convert, coradoc#320).
+    #
+    # @example Document to Markdown
+    #   md = Uniword::Converter::PlainText.new.to_markdown(document)
+    #
+    # @example Markdown to a DocumentRoot
+    #   doc = Uniword::Converter::PlainText.new.from_markdown(md_text)
+    class PlainText
+      GEMS_HINT = "coradoc-docx coradoc-markdown coradoc-adoc"
+
+      # Convert a document to Markdown.
+      #
+      # @param document [Wordprocessingml::DocumentRoot] source document
+      # @param strict [Boolean] raise when features would be dropped
+      # @return [String] the Markdown text
+      # @raise [FidelityError] in strict mode with dropped features
+      def to_markdown(document, strict: false)
+        result = to_markdown_result(document, strict: strict)
+        warn_dropped_features(result)
+        result.text
+      end
+
+      # Convert a document to Markdown with a full result record.
+      #
+      # @param document [Wordprocessingml::DocumentRoot] source document
+      # @param strict [Boolean] raise when features would be dropped
+      # @return [PlainTextResult]
+      # @raise [FidelityError] in strict mode with dropped features
+      def to_markdown_result(document, strict: false)
+        require_gems!("coradoc/docx", "coradoc/markdown")
+        drops = detect_dropped_features(document)
+        assert_strict!(drops, :markdown) if strict
+        core = with_conversion_guards(document, drops) do
+          ::Coradoc::Docx.parse_to_core(document)
+        end
+        build_result(format: :markdown, direction: :docx_to_markdown,
+                     core: core, drops: drops, text:
+                     ::Coradoc::Markdown.serialize(core))
+      end
+
+      # Parse Markdown into a document model.
+      #
+      # @param text [String] Markdown source
+      # @param strict [Boolean] raise when features would be dropped
+      # @return [Wordprocessingml::DocumentRoot]
+      def from_markdown(text, strict: false)
+        result = from_markdown_result(text, strict: strict)
+        warn_dropped_features(result)
+        result.document
+      end
+
+      # Parse Markdown into a document model with a full result record.
+      #
+      # @param text [String] Markdown source
+      # @param strict [Boolean] raise when features would be dropped
+      # @return [PlainTextResult]
+      def from_markdown_result(text, strict: false)
+        require_gems!("coradoc/docx", "coradoc/markdown")
+        core = ::Coradoc::Markdown.parse_to_core(text)
+        finish_from_core(format: :markdown,
+                         direction: :markdown_to_docx,
+                         core: core, strict: strict)
+      end
+
+      # Convert a document to AsciiDoc.
+      #
+      # @param document [Wordprocessingml::DocumentRoot] source document
+      # @param strict [Boolean] raise when features would be dropped
+      # @return [String] the AsciiDoc text
+      # @raise [FidelityError] in strict mode with dropped features
+      def to_asciidoc(document, strict: false)
+        result = to_asciidoc_result(document, strict: strict)
+        warn_dropped_features(result)
+        result.text
+      end
+
+      # Convert a document to AsciiDoc with a full result record.
+      #
+      # @param document [Wordprocessingml::DocumentRoot] source document
+      # @param strict [Boolean] raise when features would be dropped
+      # @return [PlainTextResult]
+      # @raise [FidelityError] in strict mode with dropped features
+      def to_asciidoc_result(document, strict: false)
+        require_gems!("coradoc/docx", "coradoc/asciidoc")
+        drops = detect_dropped_features(document)
+        assert_strict!(drops, :asciidoc) if strict
+        core = with_conversion_guards(document, drops) do
+          ::Coradoc::Docx.parse_to_core(document)
+        end
+        adoc_model = ::Coradoc::AsciiDoc::Transform::FromCoreModel
+          .transform(core)
+        normalize_emphasis_constraint!(adoc_model)
+        build_result(format: :asciidoc, direction: :docx_to_asciidoc,
+                     core: core, drops: drops, text: adoc_model.to_adoc)
+      end
+
+      # CoreModel carries no emphasis constraint, and the framework's
+      # flank guess can downgrade boundary-flanked runs to the
+      # constrained spelling, which does not reparse mid-word. The
+      # DOCX contract emits the unconstrained forms (`**bold**`,
+      # `__italic__`) — they parse unconditionally — so the
+      # converter restores the emphasis models' own unconstrained
+      # default after the transform.
+      def normalize_emphasis_constraint!(model)
+        model.visit do |element, _phase|
+          element.unconstrained = true if element.is_a?(
+            ::Coradoc::AsciiDoc::Model::Inline::Bold,
+          ) || element.is_a?(::Coradoc::AsciiDoc::Model::Inline::Italic)
+          element
+        end
+        model
+      end
+
+      # Parse AsciiDoc into a document model.
+      #
+      # @param text [String] AsciiDoc source
+      # @param strict [Boolean] raise when features would be dropped
+      # @return [Wordprocessingml::DocumentRoot]
+      def from_asciidoc(text, strict: false)
+        result = from_asciidoc_result(text, strict: strict)
+        warn_dropped_features(result)
+        result.document
+      end
+
+      # Parse AsciiDoc into a document model with a full result record.
+      #
+      # @param text [String] AsciiDoc source
+      # @param strict [Boolean] raise when features would be dropped
+      # @return [PlainTextResult]
+      def from_asciidoc_result(text, strict: false)
+        require_gems!("coradoc/docx", "coradoc/asciidoc")
+        core = ::Coradoc::AsciiDoc.parse_to_core(text)
+        finish_from_core(format: :asciidoc,
+                         direction: :asciidoc_to_docx,
+                         core: core, strict: strict)
+      end
+
+      private
+
+      # Lazily load the coradoc gems; raise a DependencyError with an
+      # install hint when any is missing.
+      def require_gems!(*libs)
+        libs.each { |lib| require lib }
+      rescue LoadError
+        raise DependencyError.new(GEMS_HINT, "plain-text conversion")
+      end
+
+      # Detect features present in the source document that the
+      # plain-text target drops or degrades. Order is presentation
+      # order; each check maps to a documented fidelity boundary.
+      def detect_dropped_features(document)
+        features = []
+        features << "headers/footers" unless document.header_footer_parts.empty?
+        unless document.body&.section_properties.nil?
+          features << "section properties"
+        end
+        features << "comments" if comments_present?(document)
+        if any_paragraph?(document) { |p| tracked?(p) }
+          features << "tracked changes"
+        end
+        if any_paragraph?(document) { |p| sdt?(p) } ||
+            Array(document.body&.structured_document_tags).any?
+          features << "structured document tags (unwrapped)"
+        end
+        features << "math (OMML)" if any_paragraph?(document) { |p| math?(p) }
+        features << "images" if any_paragraph?(document) { |p| drawing?(p) }
+        features
+      end
+
+      def assert_strict!(drops, format)
+        return if drops.empty?
+
+        raise FidelityError.new(format, drops)
+      end
+
+      # Rewrite hyperlink rIds to their target URLs so coradoc's
+      # writers emit real links; every mutation is restored after the
+      # conversion.
+      def with_conversion_guards(document, _drops)
+        rewrites = resolve_link_targets(document)
+        yield.tap { restore_link_targets(rewrites) }
+      end
+
+      # Rewrite w:hyperlink r:id attributes to their relationship
+      # targets so coradoc's writers emit real URLs instead of "rId1".
+      # Relationships live in document.xml.rels on loaded documents
+      # and in the IdAllocator on builder-built ones; both sources are
+      # consulted. Returns the rewrite log for restoration.
+      def resolve_link_targets(document)
+        rewrites = []
+        rels = relationship_lookup(document)
+        return rewrites if rels.empty?
+
+        each_document_hyperlink(document) do |hyperlink|
+          rel = rels[hyperlink.id.to_s]
+          next unless rel && rel[:target] &&
+            rel[:target_mode] == "External"
+
+          rewrites << [hyperlink, hyperlink.id]
+          hyperlink.id = rel[:target]
+        end
+        rewrites
+      end
+
+      # rId => { target:, target_mode: } across both relationship
+      # sources; allocator entries never override explicit rels.
+      def relationship_lookup(document)
+        lookup = {}
+        Array(document.document_rels&.relationships).each do |rel|
+          lookup[rel.id.to_s] =
+            { target: rel.target, target_mode: rel.target_mode }
+        end
+        Array(document.allocator&.all_rels).each do |entry|
+          lookup[entry[:id].to_s] ||=
+            { target: entry[:target], target_mode: entry[:target_mode] }
+        end
+        lookup
+      end
+
+      def restore_link_targets(rewrites)
+        rewrites.each { |hyperlink, original| hyperlink.id = original }
+      end
+
+      def build_result(format:, direction:, core:, drops:, text: nil,
+                       document: nil)
+        PlainTextResult.new(
+          format: format,
+          direction: direction,
+          block_counts: count_blocks(core),
+          dropped_features: drops,
+          text: text,
+          document: document,
+        )
+      end
+
+      # Serialize the CoreModel into a DocumentRoot and wrap both in a
+      # result (from_* direction).
+      def finish_from_core(format:, direction:, core:, strict:)
+        document = ::Coradoc::Docx.serialize(core)
+        build_result(format: format, direction: direction, core: core,
+                     drops: [], document: document).tap do |result|
+          assert_strict!(result.dropped_features, format) if strict
+        end
+      end
+
+      def warn_dropped_features(result)
+        return if result.clean?
+
+        result.dropped_features.each do |feature|
+          Uniword.logger.warn(
+            "plain-text conversion (#{result.direction}) dropped: #{feature}",
+          )
+        end
+      end
+
+      # ---- CoreModel block counting ---------------------------------
+
+      def count_blocks(core)
+        counts = Hash.new(0)
+        Array(core).each do |root|
+          walk_core(root, skip_self: true) do |node|
+            case node
+            when ::Coradoc::CoreModel::StructuralElement
+              counts[:headings] += 1 if heading?(node)
+            when ::Coradoc::CoreModel::Block
+              counts[:paragraphs] += 1
+            when ::Coradoc::CoreModel::ListBlock
+              counts[:lists] += 1
+            when ::Coradoc::CoreModel::Table
+              counts[:tables] += 1
+            when ::Coradoc::CoreModel::InlineElement
+              counts[:links] += 1 if link?(node)
+            end
+          end
+        end
+        counts
+      end
+
+      def heading?(element)
+        element.title && element.heading_level.to_i >= 1
+      end
+
+      def link?(inline)
+        inline.resolve_format_type == "link"
+      end
+
+      def walk_core(node, skip_self: false, &block)
+        yield node unless skip_self
+        children_of(node).each { |child| walk_core(child, &block) }
+      end
+
+      def children_of(node)
+        case node
+        when ::Coradoc::CoreModel::StructuralElement
+          Array(node.children)
+        when ::Coradoc::CoreModel::Block
+          content = node.renderable_content
+          content.is_a?(Array) ? content.grep(::Coradoc::CoreModel::Base) : []
+        when ::Coradoc::CoreModel::ListBlock
+          Array(node.items)
+        when ::Coradoc::CoreModel::Table
+          Array(node.rows).flat_map { |row| Array(row.cells) }
+        else
+          []
+        end
+      end
+
+      # ---- DocumentRoot content traversal ---------------------------
+
+      def any_paragraph?(document, &block)
+        each_document_paragraph(document).any?(&block)
+      end
+
+      def each_document_paragraph(document, &block)
+        return enum_for(:each_document_paragraph, document) unless block
+
+        body = document.body
+        return unless body
+
+        Array(body.paragraphs).each(&block)
+        Array(body.tables).each do |table|
+          each_table_paragraph(table, &block)
+        end
+      end
+
+      def each_table_paragraph(table, &block)
+        Array(table.rows).each do |row|
+          Array(row.cells).each do |cell|
+            Array(cell.paragraphs).each(&block)
+            Array(cell.tables).each do |nested|
+              each_table_paragraph(nested, &block)
+            end
+          end
+        end
+      end
+
+      def each_document_hyperlink(document, &block)
+        each_document_paragraph(document) do |paragraph|
+          Array(paragraph.hyperlinks).each(&block)
+        end
+      end
+
+      # ---- Feature predicates ---------------------------------------
+
+      def tracked?(paragraph)
+        Array(paragraph.insertions).any? ||
+          Array(paragraph.deletions).any?
+      end
+
+      def sdt?(paragraph)
+        Array(paragraph.sdts).any?
+      end
+
+      def math?(paragraph)
+        Array(paragraph.o_maths).any? || Array(paragraph.o_math_paras).any?
+      end
+
+      def drawing?(paragraph)
+        paragraph.runs.any? { |run| Array(run.drawings).any? }
+      end
+
+      def comments_present?(document)
+        # nil (no comments part) and unexpected forms count as absent;
+        # the legacy Array form is tolerated.
+        case (comments = document.comments)
+        when Uniword::CommentsPart then !comments.empty?
+        when Array then comments.any?
+        else false
+        end
+      end
+
+    end
+  end
+end

data/lib/uniword/converter/plain_text_result.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Uniword
+  module Converter
+    # Value object describing the outcome of a plain-text conversion
+    # (Converter::PlainText).
+    #
+    # Records how many blocks of each kind were converted and which
+    # document features were dropped or degraded on the way, so callers
+    # (and the CLI --json output) can surface the fidelity boundary
+    # explicitly instead of losing content silently.
+    #
+    # @example
+    #   result = converter.to_markdown_result(document)
+    #   puts result.summary
+    #   result.dropped?("comments") # => true
+    class PlainTextResult
+      # The target or source plain-text format (:markdown or :asciidoc)
+      attr_reader :format
+
+      # The conversion direction, e.g. :docx_to_markdown
+      attr_reader :direction
+
+      # Converted block counts (e.g. { headings: 2, paragraphs: 3 })
+      attr_reader :block_counts
+
+      # Features dropped or degraded during the conversion
+      attr_reader :dropped_features
+
+      # Converted plain text (to_* conversions; nil otherwise)
+      attr_reader :text
+
+      # Converted document model (from_* conversions; nil otherwise)
+      attr_reader :document
+
+      # Initialize a conversion result.
+      #
+      # @param format [Symbol] :markdown or :asciidoc
+      # @param direction [Symbol] e.g. :docx_to_markdown
+      # @param block_counts [Hash<Symbol, Integer>] converted block counts
+      # @param dropped_features [Array<String>] dropped/degraded features
+      # @param text [String, nil] converted plain text
+      # @param document [Wordprocessingml::DocumentRoot, nil] converted model
+      def initialize(format:, direction:, block_counts: {},
+                     dropped_features: [], text: nil, document: nil)
+        @format = format
+        @direction = direction
+        @block_counts = block_counts
+        @dropped_features = dropped_features
+        @text = text
+        @document = document
+      end
+
+      # Whether a feature was dropped or degraded.
+      #
+      # @param feature [String] feature name as recorded in dropped_features
+      # @return [Boolean]
+      def dropped?(feature)
+        dropped_features.include?(feature)
+      end
+
+      # Whether nothing was dropped or degraded.
+      #
+      # @return [Boolean]
+      def clean?
+        dropped_features.empty?
+      end
+
+      # Total number of converted blocks.
+      #
+      # @return [Integer]
+      def total_blocks
+        block_counts.values.sum
+      end
+
+      # Human-readable summary of the conversion.
+      #
+      # @return [String]
+      def summary
+        parts = block_counts.filter_map do |kind, count|
+          "#{count} #{kind}" if count.positive?
+        end
+        summary = "#{direction}: converted #{parts.join(', ')}"
+        summary += "; dropped: #{dropped_features.join(', ')}" unless clean?
+        summary
+      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
+        {
+          format: format,
+          direction: direction,
+          blocks: block_counts,
+          total_blocks: total_blocks,
+          dropped_features: dropped_features,
+          summary: summary,
+        }
+      end
+    end
+  end
+end

data/lib/uniword/converter.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Uniword
+  # Format converters beyond the docx/mhtml/html paths handled by
+  # FormatConverter. Currently hosts the plain-text editing round
+  # trip (Markdown / AsciiDoc) built on the optional Coradoc gems.
+  module Converter
+    autoload :PlainText, "uniword/converter/plain_text"
+    autoload :PlainTextResult, "uniword/converter/plain_text_result"
+  end
+end

data/lib/uniword/diff/document_differ.rb

@@ -222,94 +222,8 @@ module Uniword
       # @param new_paras [Array<Paragraph>]
       # @return [Array<Array(Symbol, Integer, Integer)>]
       def align_paragraphs(old_paras, new_paras)
-        old_texts = old_paras.map { |p| p.text.to_s }
-        new_texts = new_paras.map { |p| p.text.to_s }
-
-        lcs = compute_lcs(old_texts, new_texts)
-
-        result = []
-        old_i = 0
-        new_i = 0
-        lcs_idx = 0
-
-        while old_i < old_texts.size || new_i < new_texts.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
-            # LCS match at both positions -- aligned
-            old_text = old_texts[old_i]
-            new_text = new_texts[new_i]
-            action = old_text == new_text ? :kept : :modified
-            result << [action, old_i, new_i]
-            old_i += 1
-            new_i += 1
-            lcs_idx += 1
-          elsif old_in_lcs
-            # Old is part of a future LCS match, insert new as added
-            result << [:added, nil, new_i]
-            new_i += 1
-          elsif new_in_lcs
-            # New is part of a future LCS match, remove old
-            result << [:removed, old_i, nil]
-            old_i += 1
-          elsif old_i < old_texts.size && new_i < new_texts.size
-            # Neither is in LCS at this point -- treat as modified
-            result << [:modified, old_i, new_i]
-            old_i += 1
-            new_i += 1
-          elsif old_i < old_texts.size
-            result << [:removed, old_i, nil]
-            old_i += 1
-          else
-            result << [:added, nil, new_i]
-            new_i += 1
-          end
-        end
-
-        result
-      end
-
-      # Compute the LCS table and return matched index pairs.
-      #
-      # @param old_texts [Array<String>]
-      # @param new_texts [Array<String>]
-      # @return [Array<Array(Integer, Integer)>] Matched (old_i, new_i) pairs
-      def compute_lcs(old_texts, new_texts)
-        m = old_texts.size
-        n = new_texts.size
-
-        # Build LCS length table
-        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_texts[i - 1] == new_texts[j - 1]
-                         dp[i - 1][j - 1] + 1
-                       else
-                         [dp[i - 1][j], dp[i][j - 1]].max
-                       end
-          end
-        end
-
-        # Backtrack to find matches
-        matches = []
-        i = m
-        j = n
-        while i.positive? && j.positive?
-          if old_texts[i - 1] == new_texts[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
+        Lcs.alignment(old_paras.map { |p| p.text.to_s },
+                      new_paras.map { |p| p.text.to_s })
       end
 
       # Compare paragraph-level formatting between two paragraphs.