uniword 1.7.0 → 1.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34ddbf784b5b85ba8aedc6b4df9b255763e2b8014bcdea0124563e261555b32b
-  data.tar.gz: e4ef3fce0529a6db2642cbf547c28628512834339ce636f15d90c30dccba7eb2
+  metadata.gz: 7d3fa44e3714e442378ed0314c1513b673aef06059b5d02ddf92e91ea37fdca2
+  data.tar.gz: 7cddc2e3d00bd3c17b34967746642592f7ecd6bcc1fb224267c6abea92025a52
 SHA512:
-  metadata.gz: ae06c93c3b13ffffc70b0bddc7137945e4a035f2a4f75e315406547166c4423cdfe8ff8835b47ae5df50be9c6a021f500b89bd17512ae646cb3dd4c890bf8d8b
-  data.tar.gz: 7a37bcf5e4cc1ece3a92ad962757a48613be7f960890bd52017dcf8343bb1989172c7b9bd931a384dfe4bcee58c24de27b80b76e9dd4d3eca09280b078f8e3f1
+  metadata.gz: 68694569d14d4bef307578bb562dba32e5ef512d94d3dab303fac9afce6e078a3d550531fa96250228aece9b9cf687bd2aab2957c9272fd6a383ca4d6f945a85
+  data.tar.gz: abd7e230281b420942921792d1711647f6cf9f26e6e129570ef6cad8c4a680d63c0fbd2334115cd44399ec03012172dd553cbd854f6ad6ed181ae8f0197d50f6

data/CHANGELOG.md

@@ -30,6 +30,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **Breaking:** `ParagraphProperties#spacing` now returns an Array of
+  `Properties::Spacing` (was a single `Spacing` or nil), because Word
+  can emit more than one `w:spacing` inside a single `w:pPr`. Use
+  `ensure_spacing` to mutate spacing fields and the `Style` readers
+  (`spacing_before`/`spacing_after`) to read them. The readers resolve
+  conflicting values last-wins, matching Word.
 - `Uniword::Diff` module now autoloads `Semantic` (element-level
   diff sits alongside the existing text-level `DocumentDiffer`).
 - `Uniword::Batch` module now autoloads `Operation` (sibling to

data/lib/uniword/accessibility/rules/image_alt_text_rule.rb

@@ -18,14 +18,15 @@ module Uniword
           violations = []
 
           document.images.each_with_index do |image, index|
-            # Check for alt text existence
-            if image.alt_text.nil? || image.alt_text.strip.empty?
+            alt_text = image.alt_text
+
+            # Drawing#alt_text already treats a blank descr as absent.
+            if alt_text.nil?
               violations << create_violation(
                 message: "Image #{index + 1} missing alternative text",
                 element: image,
                 severity: @config[:severity] || :error,
-                suggestion: @config[:suggestion] ||
-                  "Add descriptive alternative text using image.alt_text = '...'",
+                suggestion: missing_alt_text_suggestion(image),
               )
               next # Skip quality checks if no alt text
             end
@@ -33,7 +34,7 @@ module Uniword
             # Check alt text quality if enabled
             next unless @config[:check_quality]
 
-            violations.concat(check_alt_text_quality(image, index))
+            violations.concat(check_alt_text_quality(image, alt_text, index))
           end
 
           violations
@@ -41,18 +42,39 @@ module Uniword
 
         private
 
+        # Word's older Alt Text dialog had both a Title and a Description
+        # field, and templates from that era put the description in Title.
+        # Title is a caption, not a text alternative, so the image still
+        # counts as undescribed — but say where the text already is.
+        #
+        # @param drawing [Wordprocessingml::Drawing] Drawing being reported
+        # @return [String] Suggestion text
+        def missing_alt_text_suggestion(drawing)
+          title = drawing.alt_title
+          if title
+            return "Move the drawing's docPr title (#{title.inspect}) into " \
+                   "its descr attribute; title is a caption, not alt text"
+          end
+
+          @config[:suggestion] ||
+            "Add descriptive alternative text via the drawing's " \
+            "docPr descr attribute"
+        end
+
         # Check quality of alt text
         #
-        # @param image [Image] Image to check
+        # @param image [Wordprocessingml::Drawing] Drawing to check
+        # @param alt_text [String] Alternative text read from the drawing
         # @param index [Integer] Image index
         # @return [Array<AccessibilityViolation>] Quality violations
-        def check_alt_text_quality(image, index)
+        def check_alt_text_quality(image, alt_text, index)
           violations = []
 
           # Check minimum length
-          if @config[:min_length] && image.alt_text.length < @config[:min_length]
+          if @config[:min_length] && alt_text.length < @config[:min_length]
             violations << create_violation(
-              message: "Image #{index + 1} has insufficient alt text (too short: #{image.alt_text.length} chars)",
+              message: "Image #{index + 1} has insufficient alt text " \
+                       "(too short: #{alt_text.length} chars)",
               element: image,
               severity: :warning,
               suggestion: "Alternative text should describe the image content meaningfully (min #{@config[:min_length]} chars)",
@@ -60,9 +82,10 @@ module Uniword
           end
 
           # Check maximum length
-          if @config[:max_length] && image.alt_text.length > @config[:max_length]
+          if @config[:max_length] && alt_text.length > @config[:max_length]
             violations << create_violation(
-              message: "Image #{index + 1} has excessive alt text (too long: #{image.alt_text.length} chars)",
+              message: "Image #{index + 1} has excessive alt text " \
+                       "(too long: #{alt_text.length} chars)",
               element: image,
               severity: :warning,
               suggestion: "Keep alternative text concise (max #{@config[:max_length]} chars)",
@@ -71,12 +94,12 @@ module Uniword
 
           # Check for unhelpful generic text
           unhelpful = %w[image picture photo img graphic icon]
-          alt_lower = image.alt_text.downcase
+          alt_lower = alt_text.downcase
           if unhelpful.any? do |word|
             alt_lower == word || alt_lower.start_with?("#{word} of")
           end
             violations << create_violation(
-              message: "Image #{index + 1} has generic alt text: '#{image.alt_text}'",
+              message: "Image #{index + 1} has generic alt text: '#{alt_text}'",
               element: image,
               severity: :warning,
               suggestion: "Describe what the image shows, not that it's an image",

data/lib/uniword/builder/image_builder.rb

@@ -147,6 +147,7 @@ alt_text: nil)
         inline.doc_properties = WpDrawing::DocProperties.new(
           id: deterministic_id("inline", path),
           name: File.basename(path, ".*"),
+          descr: alt_text,
         )
         inline.graphic = build_graphic(r_id, w, h)
 
@@ -227,6 +228,7 @@ alt_text: nil)
         anchor.doc_properties = WpDrawing::DocProperties.new(
           id: deterministic_id("anchor", path),
           name: File.basename(path, ".*"),
+          descr: alt_text,
         )
         anchor.graphic = build_graphic(r_id, w, h)
 

data/lib/uniword/builder/paragraph_builder.rb

@@ -98,12 +98,11 @@ module Uniword
       # @param rule [String, nil] Line rule ('auto', 'exact', 'atLeast')
       # @return [self]
       def spacing(before: nil, after: nil, line: nil, rule: nil)
-        ensure_properties.spacing ||= Properties::Spacing.new
-        props = @model.properties.spacing
-        props.before = before if before
-        props.after = after if after
-        props.line = line if line
-        props.line_rule = rule if rule
+        written = {
+          before: before, after: after, line: line, line_rule: rule
+        }.select { |_, value| value }
+        sp = ensure_properties.ensure_spacing(*written.keys)
+        written.each { |field, value| sp.public_send(:"#{field}=", value) }
         self
       end
 

data/lib/uniword/builder/sdt_builder.rb

@@ -63,19 +63,27 @@ module Uniword
 
       # Set the lock / content cannot be edited
       #
+      # Passing false writes an explicit <w:temporary w:val="false"/> rather
+      # than leaving the flag out, so the intent survives a round trip.
+      #
       # @param value [Boolean] Lock content (default true)
       # @return [self]
-      def lock(_value = true)
-        properties.temporary = Wordprocessingml::StructuredDocumentTag::Temporary.new
+      def lock(value = true)
+        properties.temporary =
+          Wordprocessingml::StructuredDocumentTag::Temporary.new(value: value)
         self
       end
 
       # Set placeholder text showing the placeholder header
       #
+      # Passing false writes an explicit <w:showingPlcHdr w:val="false"/>,
+      # the same way #lock does.
+      #
       # @param value [Boolean] Show placeholder (default true)
       # @return [self]
-      def showing_placeholder(_value = true)
-        properties.showing_placeholder_header = Wordprocessingml::StructuredDocumentTag::ShowingPlaceholderHeader.new
+      def showing_placeholder(value = true)
+        klass = Wordprocessingml::StructuredDocumentTag::ShowingPlaceholderHeader
+        properties.showing_placeholder_header = klass.new(value: value)
         self
       end
 

data/lib/uniword/builder/style_builder.rb

@@ -102,11 +102,11 @@ module Uniword
       # @param line [Integer, nil] Line spacing in twips
       # @return [self]
       def spacing(before: nil, after: nil, line: nil)
-        ensure_para_props
-        @model.pPr.spacing ||= Properties::Spacing.new
-        @model.pPr.spacing.before = before if before
-        @model.pPr.spacing.after = after if after
-        @model.pPr.spacing.line = line if line
+        written = {
+          before: before, after: after, line: line
+        }.select { |_, value| value }
+        sp = ensure_para_props.ensure_spacing(*written.keys)
+        written.each { |field, value| sp.public_send(:"#{field}=", value) }
         self
       end
 

data/lib/uniword/builder/table_builder.rb

@@ -35,8 +35,8 @@ module Uniword
       def width(value, rule: nil)
         ensure_properties
         @model.properties.table_width ||= Properties::TableWidth.new
-        @model.properties.table_width.value = value
-        @model.properties.table_width.rule = rule if rule
+        @model.properties.table_width.w = value
+        @model.properties.table_width.type = rule if rule
         self
       end
 

data/lib/uniword/builder/table_cell_builder.rb

@@ -58,9 +58,9 @@ module Uniword
       # @return [self]
       def width(value, rule: nil)
         ensure_properties
-        @model.properties.width ||= Properties::CellWidth.new
-        @model.properties.width.value = value
-        @model.properties.width.rule = rule if rule
+        @model.properties.cell_width ||= Properties::CellWidth.new
+        @model.properties.cell_width.w = value
+        @model.properties.cell_width.type = rule if rule
         self
       end
 

data/lib/uniword/builder/table_row_builder.rb

@@ -45,7 +45,8 @@ module Uniword
       # @return [self]
       def header_row(value = true)
         @model.properties ||= Wordprocessingml::TableRowProperties.new
-        @model.properties.table_header = value
+        @model.properties.tbl_header =
+          Wordprocessingml::TableRowProperties.coerce_table_header(value)
         self
       end
     end

data/lib/uniword/cli/comments_cli.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "thor"
+require "json"
+
+module Uniword
+  # Comments subcommands for Uniword CLI.
+  #
+  # Provides Word-style comment management:
+  # - list: list comments with anchored text
+  # - add: add a comment anchored to a paragraph found by search text
+  # - resolve: remove a comment and its anchor markers (Word semantics)
+  class CommentsCLI < Thor
+    include CLIHelpers
+
+    desc "list FILE", "List all comments with anchored text"
+    long_desc <<~DESC
+      Display all comments in a document with ID, author, date, text,
+      and the text of the paragraph each comment anchors.
+
+      Examples:
+        $ uniword comments list document.docx
+        $ uniword comments list document.docx --json
+    DESC
+    option :json, desc: "Output as JSON (machine-readable)",
+                  type: :boolean, default: false
+    def list(path)
+      doc = load_document(path)
+      manager = Review::ReviewManager.new(doc)
+      comment_list = manager.list_comments
+
+      if comment_list.empty?
+        say "No comments found.", :yellow
+        return
+      end
+
+      anchors = manager.comment_anchor_texts
+
+      if options[:json]
+        puts JSON.pretty_generate(comment_list.map do |comment|
+          {
+            id: comment.comment_id,
+            author: comment.author,
+            date: comment.date,
+            text: comment.text,
+            anchored_text: anchors[comment.comment_id.to_s],
+          }
+        end)
+        return
+      end
+
+      say "Comments (#{comment_list.count}):", :green
+      comment_list.each_with_index do |comment, idx|
+        say "  #{idx + 1}. ID: #{comment.comment_id}"
+        say "     Author: #{comment.author || '(unknown)'}"
+        say "     Date:   #{comment.date || '(unknown)'}"
+        say "     Text:   #{comment.text}"
+        anchored = anchors[comment.comment_id.to_s]
+        preview = anchored ? anchored[0..60] : "(unanchored)"
+        preview += "..." if anchored.to_s.length > 60
+        say "     Anchor: #{preview}"
+      end
+    rescue Uniword::Error => e
+      handle_error(e)
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    desc "add FILE", "Add a comment anchored to a paragraph"
+    long_desc <<~DESC
+      Add a comment by an author, anchored to the first paragraph whose
+      text contains the --at search phrase. Without --at, the comment is
+      anchored to the document's last paragraph (unanchored when the
+      document has no paragraphs).
+
+      Examples:
+        $ uniword comments add document.docx --author "Jane" \\
+            --text "Please verify" --at "Conclusion"
+        $ uniword comments add document.docx --author "Jane" \\
+            --text "Looks good" -o reviewed.docx
+    DESC
+    option :author, desc: "Comment author", type: :string, required: true
+    option :text, desc: "Comment text", type: :string, required: true
+    option :initials, desc: "Author initials", type: :string
+    option :at, desc: "Anchor to the first paragraph containing this " \
+                      "search text", type: :string
+    option :output, aliases: "-o", desc: "Output file (overwrites if omitted)",
+                    type: :string
+    def add(path)
+      doc = load_document(path)
+      paragraph = find_anchor_paragraph(doc, options[:at])
+      if options[:at] && paragraph.nil?
+        say "No paragraph containing '#{options[:at]}' found.", :red
+        exit 1
+      end
+
+      manager = Review::ReviewManager.new(doc)
+      comment = manager.add_comment(
+        text: options[:text],
+        author: options[:author],
+        initials: options[:initials],
+      )
+      manager.anchor_comment(comment.comment_id, paragraph)
+
+      save_output(doc, path)
+      target = options[:output] || path
+      say "Added comment #{comment.comment_id} by #{options[:author]} " \
+          "to #{target}", :green
+    rescue Uniword::Error => e
+      handle_error(e)
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    desc "resolve FILE COMMENT_ID", "Remove a comment and its anchor markers"
+    long_desc <<~DESC
+      Resolve a comment with Word semantics: the comment entry is removed
+      from word/comments.xml and its commentRangeStart, commentRangeEnd,
+      and commentReference markers are removed from the body.
+
+      Examples:
+        $ uniword comments resolve document.docx 1
+        $ uniword comments resolve document.docx 1 -o resolved.docx
+    DESC
+    option :output, aliases: "-o", desc: "Output file (overwrites if omitted)",
+                    type: :string
+    def resolve(path, comment_id)
+      doc = load_document(path)
+      manager = Review::ReviewManager.new(doc)
+
+      unless manager.resolve_comment!(comment_id)
+        say "Comment '#{comment_id}' not found.", :red
+        exit 1
+      end
+
+      save_output(doc, path)
+      say "Resolved comment '#{comment_id}'.", :green
+    rescue Uniword::Error => e
+      handle_error(e)
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    private
+
+    # Find the paragraph a new comment anchors to: the first paragraph
+    # whose text contains the search phrase, or the document's last
+    # paragraph when no phrase is given.
+    #
+    # @param doc [Uniword::Wordprocessingml::DocumentRoot]
+    # @param search_text [String, nil]
+    # @return [Wordprocessingml::Paragraph, nil]
+    def find_anchor_paragraph(doc, search_text)
+      paragraphs = []
+      FindReplace::ParagraphWalker.each_paragraph([doc.body].compact) do |p|
+        paragraphs << p
+      end
+      return paragraphs.last if search_text.nil?
+
+      paragraphs.find { |paragraph| paragraph.text.include?(search_text) }
+    end
+
+    # Save the document to the specified output path or overwrite.
+    #
+    # @param doc [Uniword::Wordprocessingml::DocumentRoot] The document
+    # @param original_path [String] The original file path
+    # @return [void]
+    def save_output(doc, original_path)
+      output_path = options[:output] || original_path
+      doc.save(output_path)
+    end
+  end
+end

data/lib/uniword/cli/diff_cli.rb

@@ -2,6 +2,7 @@
 
 require "thor"
 require "json"
+require "rainbow"
 
 module Uniword
   # Diff subcommands for Uniword CLI.
@@ -103,6 +104,57 @@ module Uniword
       handle_error(e, verbose: options[:verbose])
     end
 
+    desc "redline OLD NEW", "Create a tracked-changes (redline) DOCX"
+    long_desc <<~DESC
+      Compare two DOCX files and write the base document rewritten with
+      tracked changes (w:ins / w:del runs), the way Word's Compare
+      does. Paragraphs removed in NEW are wrapped in w:del with a
+      deleted paragraph mark, paragraphs added in NEW arrive wrapped in
+      w:ins with an inserted paragraph mark, and modified paragraphs
+      carry their word-level delta as interleaved w:del / w:ins runs.
+
+      The revision identity (author, date) is applied to every emitted
+      change. Tables pass through unchanged.
+
+      Examples:
+        $ uniword diff redline old.docx new.docx -o redline.docx
+        $ uniword diff redline old.docx new.docx --author Alice
+        $ uniword diff redline old.docx new.docx --json
+    DESC
+    option :output, aliases: "-o", desc: "Output DOCX path",
+                    type: :string
+    option :author, desc: "Revision author for emitted changes",
+                    type: :string, default: "uniword"
+    option :date, desc: "Revision date (ISO 8601) for emitted changes",
+                  type: :string
+    option :json, desc: "Output summary as JSON", type: :boolean,
+                  default: false
+    def redline(old_path, new_path)
+      validate_file_exists(old_path)
+      validate_file_exists(new_path)
+
+      base = load_document(old_path)
+      revised = load_document(new_path)
+      result = Uniword::Diff::Redliner.new(
+        base, revised,
+        author: options[:author], date: options[:date]
+      ).redline
+
+      output = options[:output] || default_redline_path(old_path)
+      result.document.save(output)
+
+      if options[:json]
+        puts result.to_json
+      else
+        puts Rainbow("  Redline written to #{output}").green.bright
+        puts "  #{result.summary}"
+      end
+    rescue Uniword::Error => e
+      handle_error(e)
+    rescue StandardError => e
+      handle_error(e)
+    end
+
     private
 
     # Build options hash for DocumentDiffer from CLI options.
@@ -115,6 +167,14 @@ module Uniword
       }
     end
 
+    # Default redline output path: base name of OLD with a .redline
+    # suffix, e.g. contract.docx -> contract.redline.docx.
+    def default_redline_path(old_path)
+      dirname = File.dirname(old_path)
+      basename = File.basename(old_path, ".*")
+      File.join(dirname, "#{basename}.redline.docx")
+    end
+
     def validate_file_exists(path)
       return if File.exist?(path)
 

data/lib/uniword/cli/main.rb

@@ -536,6 +536,78 @@ module Uniword
       handle_error(e, verbose: options[:verbose])
     end
 
+    desc "to md|adoc INPUT", "Convert a DOCX to Markdown or AsciiDoc"
+    long_desc <<~DESC
+      Convert a Word document to a plain-text editing format -- Markdown
+      or AsciiDoc -- through the Coradoc CoreModel bridge.
+
+      Carried: headings h1-h6, paragraphs, bold/italic/underline/
+      strikethrough, lists, tables with header rows, links, bookmarks.
+      Dropped or degraded features (headers/footers, comments, tracked
+      changes, SDTs, math, images, footnotes) are reported; --strict
+      fails instead of losing them.
+
+      Examples:
+        $ uniword to md report.docx
+        $ uniword to adoc report.docx -o report.adoc
+        $ uniword to md report.docx -o - --strict
+    DESC
+    option :output, aliases: "-o", type: :string,
+                    desc: "Output path ('-' for stdout; " \
+                          "default: <input>.md/.adoc)"
+    option :strict, type: :boolean, default: false,
+                    desc: "Fail when fidelity loss would occur"
+    option :json, type: :boolean, default: false,
+                  desc: "Report as JSON (requires an output file)"
+    def to(format, input_path)
+      validate_plain_text_json!
+      result = Cli::PlainTextCommand.convert_to(
+        format, input_path, strict: options[:strict]
+      )
+      output_path = options[:output] || Cli::PlainTextCommand.default_output(
+        input_path, Cli::PlainTextCommand.extension_for(format)
+      )
+      Cli::PlainTextCommand.write_text(result, output_path)
+      report_plain_text(result, input_path, output_path)
+    rescue Uniword::Error => e
+      handle_error(e)
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    desc "from md|adoc INPUT", "Convert Markdown or AsciiDoc to a DOCX"
+    long_desc <<~DESC
+      Convert a Markdown or AsciiDoc file to a Word document through
+      the Coradoc CoreModel bridge. Headings become Heading styles,
+      lists get numbering, tables keep their header rows, and
+      AsciiDoc links become real hyperlinks.
+
+      Examples:
+        $ uniword from md notes.md
+        $ uniword from adoc report.adoc -o report.docx
+        $ uniword from md notes.md --json
+    DESC
+    option :output, aliases: "-o", type: :string,
+                    desc: "Output DOCX path (default: <input>.docx)"
+    option :strict, type: :boolean, default: false,
+                    desc: "Fail when fidelity loss would occur"
+    option :json, type: :boolean, default: false,
+                  desc: "Report as JSON"
+    def from(format, input_path)
+      result = Cli::PlainTextCommand.convert_from(
+        format, input_path, strict: options[:strict]
+      )
+      output_path = options[:output] || Cli::PlainTextCommand.default_output(
+        input_path, ".docx"
+      )
+      result.document.save(output_path)
+      report_plain_text(result, input_path, output_path)
+    rescue Uniword::Error => e
+      handle_error(e)
+    rescue StandardError => e
+      handle_error(e)
+    end
+
     # Register subcommands
     desc "theme SUBCOMMAND", "Manage document themes"
     subcommand "theme", ThemeCLI
@@ -561,6 +633,13 @@ module Uniword
     desc "review SUBCOMMAND", "Review comments and tracked changes"
     subcommand "review", ReviewCLI
 
+    desc "comments SUBCOMMAND", "Manage document comments"
+    subcommand "comments", CommentsCLI
+
+    desc "revisions SUBCOMMAND",
+         "Tracked changes (alias of review changes/accept/reject)"
+    subcommand "revisions", RevisionsCLI
+
     desc "diff SUBCOMMAND", "Compare two DOCX files"
     subcommand "diff", DiffCLI
 
@@ -592,6 +671,31 @@ module Uniword
 
     private
 
+    # -- plain-text (to/from) helpers -----------------------------------
+
+    # --json pairs with an output file; stdout text and a JSON report
+    # cannot share the stream.
+    def validate_plain_text_json!
+      return unless options[:json] && options[:output] == "-"
+
+      say("Error: --json cannot be combined with '-o -'", :red)
+      exit 1
+    end
+
+    def report_plain_text(result, input_path, output_path)
+      if options[:json]
+        require "json"
+        puts JSON.pretty_generate(
+          result.to_h.merge(input: input_path, output: output_path)
+        )
+        return
+      end
+
+      say result.summary, result.clean? ? :green : :yellow
+      destination = output_path == "-" ? "stdout" : output_path
+      say "Converted #{input_path} -> #{destination}", :green
+    end
+
     # -- find-replace helpers -------------------------------------------
 
     # Normalize --scope arguments. `[:all]` collapses to `:all`; any