uniword 1.6.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1153bb3528efaa764919405fb7e3ac11e0e9aedcaae81e6dd0b692293e3876a2
-  data.tar.gz: 0e59bf185f59fc2377dc56c1dd1bfacbc773814d47dcef9f19bb6f855cf0298c
+  metadata.gz: f3edc29b5332204a6bf88fdd016239deab4b9694b8f02a823482fc0d5c3e857b
+  data.tar.gz: b02521733dd3189181864a89824e30c23eb04cd2112abaded49e6bf8643a43b9
 SHA512:
-  metadata.gz: 540da6a280c292c6563daf77a1c024fefbc1266048d7fab197cff2e7bb7d0529d2953e1cc596d8b426668702adc03a3b1821645a8bd028fc6d71cfe937862a0c
-  data.tar.gz: 9543bd3d00ce96e4d47480f5db92a05ab60a7fc1a6e85cf60037ace089106f703f30d6be825dcaa939319c5fe559d5e35b9669f8103a6c9cabd8c5c4415552f1
+  metadata.gz: ee58e9718495648ea4516db97b921cb973e79787b5745cb852593614f1ab136716f7fceecf7de9a8b093f1dd361c43282cb3841dd9acd6b32c51f3c0d6afd2ff
+  data.tar.gz: d55e30fb35e6b199429a8f1d5379319945a281bc2a81f132b2f2efe558ee212cc33c4af90a0fd2884cd211414a34faad9269b0fa44d75005d3cb61bc10cfd00f

data/exe/uniword

@@ -10,5 +10,14 @@ if defined?(RubyVM::YJIT) && !RubyVM::YJIT.enabled? &&
   RubyVM::YJIT.enable
 end
 
+# POSIX NO_COLOR convention: suppress colored CLI output.
+if ENV["NO_COLOR"] && !ENV["NO_COLOR"].empty?
+  require "uniword/cli/no_color"
+end
+
+# Never let a task's return value become the process exit status:
+# success is 0, and failures raise SystemExit inside `start`
+# (exit_on_failure? / handle_error).
 require "uniword"
 Uniword::CLI.start(ARGV)
+exit 0

data/lib/uniword/accessibility/accessibility_report.rb

@@ -46,6 +46,14 @@ module Uniword
         errors.empty?
       end
 
+      # Report-contract predicate shared with Quality::QualityReport:
+      # true when the document has no error-level violations.
+      #
+      # @return [Boolean]
+      def valid?
+        compliant?
+      end
+
       # Get all error-level violations
       #
       # @return [Array<AccessibilityViolation>] Error violations

data/lib/uniword/cli/completions.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Cli
+    # Builds shell completion scripts from live CLI metadata so new
+    # commands appear in completions without editing the scripts.
+    module Completions
+      BUILTINS = %w[help completions].freeze
+
+      module_function
+
+      # @param shell [String] "bash", "zsh", or "fish"
+      # @param root [Class] the root Thor class (Uniword::CLI)
+      # @return [String] completion script
+      def script(shell, root:)
+        commands = root.all_commands.keys - BUILTINS
+        subcommands = subcommand_map(root)
+
+        case shell
+        when "bash" then bash(commands, subcommands)
+        when "zsh"  then zsh(commands, subcommands)
+        when "fish" then fish(commands, subcommands)
+        else
+          raise ArgumentError,
+                "unsupported shell: #{shell.inspect} (bash|zsh|fish)"
+        end
+      end
+
+      # Map command name → registered subcommand Thor class, derived
+      # from class names (ThemeCLI → "theme"), so `subcommand` call
+      # sites stay the single source of truth.
+      # Space-separated subcommand word list for one class.
+      def words_for(klass)
+        klass.all_commands.keys.reject { |c| c == "help" }.join(" ")
+      end
+
+      def subcommand_map(root)
+        root.subcommand_classes.filter_map do |name, klass|
+          [name, klass]
+        end.to_h
+      end
+
+      def bash(commands, subcommands)
+        cmds = commands.join(" ")
+        script = <<~BASH
+          # uniword bash completion — generated by `uniword completions bash`
+          _uniword() {
+            local cur="${COMP_WORDS[COMP_CWORD]}"
+            local prev="${COMP_WORDS[COMP_CWORD-1]}"
+            local cmds="#{cmds}"
+        BASH
+        subcommands.each do |name, klass|
+          words = words_for(klass)
+          script << "  if [ \"$prev\" = \"#{name}\" ]; then\n    " \
+                    "COMPREPLY=( $(compgen -W \"#{words}\" " \
+                    "-- \"$cur\") )\n    return\n  fi\n"
+        end
+        script << "  COMPREPLY=( $(compgen -W \"$cmds\" -- \"$cur\") )\n" \
+                  "}\n" \
+                  "complete -F _uniword uniword\n"
+        script
+      end
+
+      def zsh(commands, subcommands)
+        script = <<~ZSH
+          #compdef uniword
+          # uniword zsh completion — generated by `uniword completions zsh`
+          _uniword() {
+            local -a cmds
+            cmds=(#{commands.map { |c| "'#{c}'" }.join(' ')})
+            _describe 'command' cmds
+        ZSH
+        subcommands.each do |name, klass|
+          words = words_for(klass).split.map { |c| "'#{c}'" }.join(" ")
+          script << "  if (( CURRENT == 2 )) && [[ #{name} == * ]]; " \
+                    "then\n    local -a sub\n    sub=(#{words})\n    " \
+                    "_describe '#{name} command' sub\n  fi\n"
+        end
+        script << "}\n"
+        script
+      end
+
+      def fish(commands, subcommands)
+        script = +<<~FISH
+          # uniword fish completion — generated by `uniword completions fish`
+        FISH
+        commands.each do |c|
+          script << "complete -c uniword -n '__fish_use_subcommand' -a '#{c}'\n"
+        end
+        subcommands.each do |name, klass|
+          words = words_for(klass)
+          script << "complete -c uniword -n '__fish_seen_subcommand_from " \
+                    "#{name}' -a '#{words}'\n"
+        end
+        script
+      end
+    end
+  end
+end

data/lib/uniword/cli/generate_cli.rb

@@ -10,6 +10,11 @@ module Uniword
   class GenerateCLI < Thor
     include CLIHelpers
 
+    # `uniword generate INPUT OUTPUT ...` dispatches straight to the
+    # generate task; the explicit `generate generate ...` form stays
+    # valid for backwards compatibility.
+    default_task :generate
+
     desc "generate INPUT OUTPUT",
          "Generate DOCX from structured text"
     long_desc <<~DESC

data/lib/uniword/cli/help_switch.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Cli
+    # Rewrites help/version flag invocations before Thor dispatch so
+    # help works on tasks with required arguments:
+    #
+    #   uniword convert --help        → uniword help convert
+    #   uniword images add --help     → uniword help images add
+    #   uniword --help / -h           → root help
+    #   uniword --version / -V        → uniword version
+    #
+    # The rewrite only fires when the help/version flag is the first
+    # flag-like token and everything before it looks like a task path
+    # (no options), so real option values (e.g. `--from docx`) are
+    # never mistaken for the chain.
+    module HelpSwitch
+      HELP_FLAGS = %w[--help -h].freeze
+      VERSION_FLAGS = %w[--version -V].freeze
+
+      def start(given_args = ARGV, config = {})
+        args = given_args.map(&:to_s)
+
+        if (help_idx = args.index { |a| HELP_FLAGS.include?(a) })
+          chain = args[0...help_idx]
+          if option_free_task_path?(chain)
+            return super(chain.unshift("help"), config)
+          end
+        end
+
+        if args.size == 1 && VERSION_FLAGS.include?(args[0])
+          return super(["version"], config)
+        end
+
+        super
+      end
+
+      private
+
+      def option_free_task_path?(chain)
+        chain.all? { |a| !a.start_with?("-") }
+      end
+    end
+  end
+end

data/lib/uniword/cli/helpers.rb

@@ -10,6 +10,7 @@ module Uniword
   module CLIHelpers
     def self.included(base)
       base.extend(ClassMethods)
+      base.extend(Cli::HelpSwitch)
     end
 
     module ClassMethods

data/lib/uniword/cli/main.rb

@@ -20,16 +20,22 @@ module Uniword
     long_desc <<~DESC
       Convert a document from one format to another.
 
-      Supported formats: DOCX, MHTML, HTML
+      Supported formats: DOCX, DOCM, DOTX, DOTM, MHTML/MHT, HTML
+
+      Use "-" as OUTPUT to write to stdout (binary formats print raw
+      bytes; pipe or redirect them).
 
       Examples:
         $ uniword convert input.docx output.mhtml
         $ uniword convert input.mhtml output.docx --verbose
         $ uniword convert input.html output.docx
+        $ uniword convert input.docx output.html
+        $ uniword convert input.docx - > converted.docx
     DESC
     option :from, aliases: "-f", desc: "Input format (docx/mhtml/html)",
                   type: :string
-    option :to, aliases: "-t", desc: "Output format (docx/mhtml)", type: :string
+    option :to, aliases: "-t", desc: "Output format (docx/mhtml/html)",
+                type: :string
     option :verbose, aliases: "-v", desc: "Verbose output", type: :boolean,
                      default: false
     def convert(input_path, output_path)
@@ -68,15 +74,30 @@ module Uniword
     DESC
     option :verbose, aliases: "-v", desc: "Show detailed information", type: :boolean,
                      default: false
+    option :json, type: :boolean, default: false,
+                  desc: "Output statistics as JSON (machine-readable)"
     def info(path)
-      say "Analyzing #{path}...", :green
-
       detector = ::Uniword::FormatDetector.new
       format = detector.detect(path)
-      say "\nFormat: #{format.to_s.upcase}", :cyan
-
       doc = load_document(path)
 
+      if options[:json]
+        require "json"
+        stats = {
+          path: path,
+          format: format.to_s.upcase,
+          paragraphs: doc.paragraphs.count,
+          tables: doc.tables.count,
+          text_length: doc.text.length,
+          styles: doc.styles_configuration&.styles&.count || 0,
+        }
+        puts JSON.pretty_generate(stats)
+        return
+      end
+
+      say "Analyzing #{path}...", :green
+      say "\nFormat: #{format.to_s.upcase}", :cyan
+
       say "\nDocument Statistics:", :cyan
       say "  Paragraphs: #{doc.paragraphs.count}"
       say "  Tables: #{doc.tables.count}"
@@ -130,15 +151,32 @@ module Uniword
     DESC
     option :verbose, aliases: "-v", desc: "Show detailed validation results", type: :boolean,
                      default: false
+    option :json, type: :boolean, default: false,
+                  desc: "Output the validation report as JSON (machine-readable)"
     def validate(path)
-      say "Validating #{path}...", :green
-
       doc = load_document(path)
-      say "File format is valid", :green
 
       issues = Uniword::Validation::Engine.run(
         Uniword::Validation::Rules::ModelContext.new(doc),
       )
+
+      if options[:json]
+        require "json"
+        puts JSON.pretty_generate(
+          path: path,
+          valid: issues.none?(&:error?),
+          issues: issues.map { |i|
+            { code: i.code, severity: i.severity,
+              part: i.part, message: i.message }
+          },
+        )
+        exit 1 if issues.any?(&:error?)
+        return
+      end
+
+      say "Validating #{path}...", :green
+      say "File format is valid", :green
+
       report_validation_issues(issues)
       report_content_presence(doc)
 
@@ -191,6 +229,8 @@ module Uniword
     long_desc <<~DESC
       Run document quality and accessibility checks.
 
+      Exits 1 when any report has error-level findings.
+
       Examples:
         $ uniword check document.docx
         $ uniword check document.docx --type accessibility
@@ -202,8 +242,14 @@ module Uniword
                      default: false
     option :json, desc: "Output JSON report", type: :boolean, default: false
     def check(path)
-      doc = load_document(path)
       check_type = options[:type]
+      unless CHECK_TYPES.include?(check_type)
+        say("Unknown check type: #{check_type} " \
+            "(valid: #{CHECK_TYPES.join(', ')})", :red)
+        exit 1
+      end
+
+      doc = load_document(path)
 
       reports = {}
 
@@ -219,14 +265,15 @@ module Uniword
 
       if options[:json]
         require "json"
-        output = reports.transform_values do |r|
-          { valid: r.valid?,
-            issues: r.is_a?(Uniword::Quality::CheckReport) ? r.issues.count : 0 }
+        output = reports.transform_values do |report|
+          { valid: report.valid?, issues: report.violations.count }
         end
         puts JSON.pretty_generate(output)
       else
         display_check_reports(reports)
       end
+
+      exit 1 if reports.values.any? { |report| !report.valid? }
     rescue Uniword::Error => e
       handle_error(e)
     rescue StandardError => e
@@ -383,6 +430,22 @@ module Uniword
       say "Uniword version #{Uniword::VERSION}", :green
     end
 
+    desc "completions [SHELL]", "Print shell completion script (bash|zsh|fish)"
+    long_desc <<~DESC
+      Print a self-contained shell completion script.
+
+      Install:
+        $ uniword completions bash >> ~/.bashrc
+        $ uniword completions zsh >> ~/.zshrc
+        $ uniword completions fish > ~/.config/fish/completions/uniword.fish
+    DESC
+    def completions(shell = "bash")
+      require "uniword/cli/completions"
+      puts Cli::Completions.script(shell, root: self.class)
+    rescue ArgumentError => e
+      handle_error(e)
+    end
+
     desc "redact INPUT OUTPUT", "Redact PII patterns from a document"
     long_desc <<~DESC
       Replace PII patterns (SSN, email, phone, credit card, IPv4)
@@ -406,6 +469,8 @@ module Uniword
     option :verbose, aliases: "-v", type: :boolean, default: false,
                      desc: "Show per-pattern counts"
     def redact(input_path, output_path)
+      validate_scopes!(options[:scope])
+      validate_redact_patterns!(options[:pattern])
       doc = load_document(input_path)
       patterns = resolve_redact_patterns(options[:pattern])
       result = doc.redact(patterns: patterns,
@@ -451,6 +516,8 @@ module Uniword
     option :verbose, aliases: "-v", type: :boolean, default: false,
                      desc: "Show per-scope counts"
     def find_replace(input_path, output_path, pattern, replacement)
+      validate_scopes!(options[:scope])
+      validate_regex!(pattern) if options[:regex]
       scopes = expand_scopes(options[:scope])
       doc = load_document(input_path)
       result = run_find_replace(doc, pattern, replacement, scopes)
@@ -541,6 +608,36 @@ module Uniword
       symbols
     end
 
+    # Valid values for `check --type`.
+    CHECK_TYPES = %w[all quality accessibility].freeze
+
+    def validate_scopes!(scopes)
+      valid = ["all"] + Uniword::FindReplace::Engine::ALL_SCOPES.map(&:to_s)
+      unknown = Array(scopes).map(&:to_s) - valid
+      return if unknown.empty?
+
+      say("Unknown scope: #{unknown.join(', ')} " \
+          "(valid: #{valid.join(', ')})", :red)
+      exit 1
+    end
+
+    def validate_regex!(pattern)
+      Regexp.new(pattern)
+    rescue RegexpError => e
+      say("Invalid regular expression: #{e.message}", :red)
+      exit 1
+    end
+
+    def validate_redact_patterns!(names)
+      valid = [:pii] + Uniword::Redact::PatternLibrary.all.map(&:name)
+      unknown = Array(names).map(&:to_sym) - valid
+      return if unknown.empty?
+
+      say("Unknown pattern: #{unknown.join(', ')} " \
+          "(valid: #{valid.join(', ')})", :red)
+      exit 1
+    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)
@@ -679,14 +776,14 @@ module Uniword
         label = type.to_s.capitalize
         if report.valid?
           say("#{label}: No issues found", :green)
-        else
-          issue_count = report.is_a?(Uniword::Quality::CheckReport) ? report.issues.count : "?"
-          say("#{label}: #{issue_count} issue(s) found", :yellow)
-          if options[:verbose] && report.is_a?(Uniword::Quality::CheckReport)
-            report.issues.each do |issue|
-              say("  - #{issue}", :yellow)
-            end
-          end
+          next
+        end
+
+        say("#{label}: #{report.violations.count} issue(s) found", :yellow)
+        next unless options[:verbose]
+
+        report.violations.each do |violation|
+          say("  - #{violation.message}", :yellow)
         end
       end
     end

data/lib/uniword/cli/no_color.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Cli
+    # POSIX NO_COLOR convention (https://no-color.org/): when the
+    # environment variable is set (to any non-empty value), colored
+    # CLI output must be suppressed. Prepended onto Thor's shell only
+    # when the variable is present, so the zero-cost path is the norm.
+    module NoColor
+      def color?
+        return false if ENV["NO_COLOR"] && !ENV["NO_COLOR"].empty?
+
+        super
+      end
+    end
+  end
+end
+
+require "thor/shell/basic"
+
+Thor::Shell::Basic.prepend(Uniword::Cli::NoColor)

data/lib/uniword/document_factory.rb

@@ -80,7 +80,7 @@ module Uniword
       rescue Zip::Error => e
         raise CorruptedFileError.new(path.to_s,
                                      "Invalid ZIP structure: #{e.message}")
-      rescue Nokogiri::XML::SyntaxError => e
+      rescue Moxml::ParseError => e
         raise CorruptedFileError.new(path.to_s, "Invalid XML: #{e.message}")
       rescue StandardError => e
         # Re-raise our custom errors
@@ -143,7 +143,7 @@ module Uniword
       rescue Zip::Error => e
         raise CorruptedFileError.new(path.to_s,
                                      "Invalid ZIP structure: #{e.message}")
-      rescue Nokogiri::XML::SyntaxError => e
+      rescue Moxml::ParseError => e
         raise CorruptedFileError.new(path.to_s, "Invalid XML: #{e.message}")
       rescue StandardError => e
         # Re-raise our custom errors

data/lib/uniword/document_writer.rb

@@ -49,36 +49,57 @@ module Uniword
     #
     # @example Save with explicit format
     #   writer.save("output.mht", format: :mhtml)
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/CyclomaticComplexity
     def save(path, format: :auto, profile: nil, validate: nil)
       validate_path(path)
 
+      if path == "-"
+        # stdout: "-" cannot carry an extension; default to DOCX when
+        # the caller does not pin the format (use --to to override).
+        format = :docx if format == :auto
+        write_to_stream($stdout, format: format, validate: validate)
+        return
+      end
+
       format = infer_format(path) if format == :auto
 
       case format
       when :docx, :docm
         Docx::Package.to_file(document, path, profile: profile,
-                                            validate: validate)
+                                              validate: validate)
       when :dotx, :dotm
         Ooxml::DotxPackage.to_file(document, path, profile: profile,
-                                                 validate: validate)
+                                                   validate: validate)
       when :mhtml
         Mhtml::MhtmlPackage.to_file(document, path)
+      when :html
+        File.write(path, html_document)
       else
         raise ArgumentError,
               "No handler registered for format: #{format.inspect}"
       end
     end
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/CyclomaticComplexity
+
+    # Render the document as a standalone HTML string.
+    #
+    # @return [String] HTML document
+    def html_document
+      Transformation::OoxmlToHtmlConverter.document_to_html(document)
+    end
 
     # Infer the format from file extension.
     #
     # @param path [String] The file path
-    # @return [Symbol] The inferred format (:docx, :mhtml)
+    # @return [Symbol] The inferred format (:docx, :mhtml, :html)
     # @raise [ArgumentError] if format cannot be inferred
     #
     # @example Infer format
     #   format = writer.infer_format("output.docx")
     #   # => :docx
-    def infer_format(path)
+    def infer_format(path) # rubocop:disable Metrics/CyclomaticComplexity
       extension = File.extname(path).downcase
 
       case extension
@@ -90,16 +111,17 @@ module Uniword
         :dotx
       when ".dotm"
         :dotm
-      when ".mhtml", ".mht"
-        :mhtml
-      when ".doc"
-        # .doc can be MHTML saved with Word (not binary old Word format)
-        # We don't support binary .doc output, but MHTML .doc is valid
+      when ".html"
+        :html
+      # .doc can be MHTML saved with Word (not binary old Word format)
+      # We don't support binary .doc output, but MHTML .doc is valid
+      when ".mhtml", ".mht", ".doc"
         :mhtml
       else
         raise ArgumentError,
               "Cannot infer format from extension: #{extension}. " \
-              "Supported extensions: .docx, .docm, .dotx, .dotm, .mhtml, .mht"
+              "Supported extensions: .docx, .docm, .dotx, .dotm, " \
+              ".html, .mhtml, .mht, .doc"
       end
     end
 

data/lib/uniword/find_replace/paragraph_walker.rb

@@ -2,15 +2,21 @@
 
 module Uniword
   module FindReplace
-    # Walks an enumerable of containers (Body, TableCell, SDT, ...)
-    # and yields every Paragraph reachable. Used by all scopes that
-    # traverse paragraph-bearing parts (body, headers, footers,
-    # footnotes, endnotes, comments).
+    # Walks an enumerable of containers (Body, TableCell, Header,
+    # Footer, Footnote, Endnote, Comment) and yields every Paragraph
+    # reachable. Used by all scopes that traverse paragraph-bearing
+    # parts (body, headers, footers, footnotes, endnotes, comments).
+    #
+    # Container classes map different subsets of OOXML block-level
+    # content, so dispatch is explicit per class (mirrors
+    # Docx::DocumentStatistics):
+    # - Body maps paragraphs, tables, and structured document tags
+    # - TableCell, Header, Footer map paragraphs and tables
+    # - Footnote, Endnote, Comment map paragraphs only
     module ParagraphWalker
       module_function
 
-      # @param containers [Enumerable<#paragraphs, #tables,
-      #   #structured_document_tags>] containers to walk
+      # @param containers [Enumerable<#paragraphs>] containers to walk
       # @yieldparam paragraph [Wordprocessingml::Paragraph]
       # @return [void]
       def each_paragraph(containers, &block)
@@ -23,13 +29,37 @@ module Uniword
       # @yieldparam paragraph [Wordprocessingml::Paragraph]
       # @return [void]
       def walk_container(container, &block)
-        container.paragraphs&.each(&block)
-        walk_tables(container.tables, &block) if container.tables
-        if container.structured_document_tags
-          walk_sdts(container.structured_document_tags, &block)
+        case container
+        when Wordprocessingml::Body
+          walk_body(container, &block)
+        else
+          walk_non_body(container, &block)
         end
       end
 
+      # Body is the only container class that maps structured
+      # document tags.
+      def walk_body(body, &block)
+        body.paragraphs&.each(&block)
+        walk_tables(body.tables, &block)
+        walk_sdts(body.structured_document_tags, &block)
+      end
+
+      # TableCell, Header, and Footer map tables; Footnote, Endnote,
+      # and Comment map paragraphs only.
+      def walk_non_body(container, &block)
+        container.paragraphs&.each(&block)
+        return unless table_bearing?(container)
+
+        walk_tables(container.tables, &block)
+      end
+
+      def table_bearing?(container)
+        container.is_a?(Wordprocessingml::TableCell) ||
+          container.is_a?(Wordprocessingml::Header) ||
+          container.is_a?(Wordprocessingml::Footer)
+      end
+
       def walk_tables(tables, &block)
         tables.each do |table|
           walk_table_rows(table, &block) if table.rows
@@ -48,13 +78,20 @@ module Uniword
         end
       end
 
+      # SDT content (sdtContent) is itself a block-level container
+      # with paragraphs, tables, and nested SDTs.
       def walk_sdts(sdts, &block)
         sdts.each do |sdt|
-          sdt.paragraphs&.each(&block)
+          next unless sdt.content
+
+          sdt.content.paragraphs&.each(&block)
+          walk_tables(sdt.content.tables, &block)
+          walk_sdts(sdt.content.sdts, &block)
         end
       end
 
-      private_class_method :walk_container, :walk_tables, :walk_table_rows,
+      private_class_method :walk_container, :walk_body, :walk_non_body,
+                           :table_bearing?, :walk_tables, :walk_table_rows,
                            :walk_table_cells, :walk_sdts
     end
   end