uniword 1.5.1 → 1.5.3

data/lib/uniword/redact/engine.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Redact
+    # Redaction orchestrator. Runs each pattern through the
+    # FindReplace engine and aggregates per-pattern counts.
+    #
+    # Open/closed: adding a new pattern = `PatternLibrary.register`
+    # call. Engine unchanged.
+    class Engine
+      # @param document [Wordprocessingml::DocumentRoot]
+      # @param patterns [Array<Pattern>, :pii] patterns to apply
+      #   (`:pii` selects the default library)
+      # @param scope [Symbol, Array<Symbol>, :all] find-replace scope
+      def initialize(document:, patterns: :pii, scope: :all)
+        @document = document
+        @patterns = resolve_patterns(patterns)
+        @scope = scope
+      end
+
+      # @return [Redact::Result]
+      def run
+        result = Result.new
+        return result if @patterns.empty?
+
+        @patterns.each do |pattern|
+          matcher = FindReplace::RegexMatcher.new(pattern: pattern.regex,
+                                                  replacement: pattern.replacement)
+          fr = FindReplace::Engine.new(document: @document,
+                                       matcher: matcher,
+                                       scopes: @scope).run
+          result.add(pattern.name, fr.count)
+        end
+        result
+      end
+
+      private
+
+      def resolve_patterns(patterns)
+        return PatternLibrary.all if patterns == :pii
+        return [] if patterns.nil? || patterns.empty?
+
+        list = Array(patterns)
+        if list.all?(Symbol)
+          PatternLibrary.select(list)
+        else
+          list
+        end
+      end
+    end
+  end
+end

data/lib/uniword/redact/pattern.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Redact
+    # One redaction pattern: a regex plus a label that classifies the
+    # kind of PII it matches.
+    class Pattern
+      attr_reader :name, :regex, :replacement, :description
+
+      # @param name [Symbol] pattern identifier (e.g. :ssn, :email)
+      # @param regex [Regexp] what to match
+      # @param replacement [String] replacement text (default "[REDACTED]")
+      # @param description [String] human-readable pattern description
+      def initialize(name:, regex:, replacement: "[REDACTED]",
+                     description: nil)
+        @name = name
+        @regex = regex
+        @replacement = replacement
+        @description = description
+      end
+    end
+  end
+end

data/lib/uniword/redact/pattern_library.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Redact
+    # Built-in library of common PII patterns. Open/closed: callers
+    # can register custom patterns via `PatternLibrary.register`.
+    class PatternLibrary
+      DEFAULT_PATTERNS = [
+        # US Social Security Number: AAA-GG-SSSS (no all-zeros groups)
+        Pattern.new(name: :ssn,
+                    regex: /\b(?!000|666|9\d{2})\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b/,
+                    description: "US Social Security Number"),
+        # Email address
+        Pattern.new(name: :email,
+                    regex: /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i,
+                    description: "Email address"),
+        # US phone: (555) 555-5555 or 555-555-5555
+        Pattern.new(name: :phone,
+                    regex: /\b\(?\d{3}\)?[-.\s]\d{3}[-.\s]\d{4}\b/,
+                    description: "US phone number"),
+        # Credit card number: 13-19 digits, optional separators
+        Pattern.new(name: :credit_card,
+                    regex: /\b(?:\d[ -]*?){13,19}\b/,
+                    description: "Credit card number"),
+        # IPv4 address
+        Pattern.new(name: :ipv4,
+                    regex: /\b(?:\d{1,3}\.){3}\d{1,3}\b/,
+                    description: "IPv4 address"),
+      ].freeze
+
+      # All registered patterns, in registration order.
+      #
+      # @return [Array<Pattern>]
+      def self.all
+        DEFAULT_PATTERNS + @custom.to_a
+      end
+
+      # Select patterns by name.
+      #
+      # @param names [Array<Symbol>, :all] names to select, or :all
+      # @return [Array<Pattern>]
+      def self.select(names)
+        return all if names == :all
+
+        list = all
+        Array(names).filter_map { |n| list.find { |p| p.name == n } }
+      end
+
+      # Register a custom pattern. Append-only.
+      #
+      # @param pattern [Pattern]
+      # @return [void]
+      def self.register(pattern)
+        (@custom ||= []) << pattern
+      end
+
+      @custom = []
+    end
+  end
+end

data/lib/uniword/redact/result.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Redact
+    # Aggregated redaction result.
+    class Result
+      attr_reader :by_pattern
+
+      def initialize
+        @by_pattern = Hash.new { |h, k| h[k] = 0 }
+      end
+
+      # @param name [Symbol] pattern name
+      # @param count [Integer] substitutions for this pattern
+      # @return [void]
+      def add(name, count)
+        @by_pattern[name] += count
+      end
+
+      # Total substitutions across all patterns.
+      #
+      # @return [Integer]
+      def count
+        @by_pattern.values.sum
+      end
+
+      # Patterns that matched at least once.
+      #
+      # @return [Array<Symbol>]
+      def patterns_matched
+        @by_pattern.select { |_, c| c.positive? }.keys
+      end
+
+      # True when zero substitutions were made.
+      #
+      # @return [Boolean]
+      def empty?
+        count.zero?
+      end
+    end
+  end
+end

data/lib/uniword/redact.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Uniword
+  # Document redaction and anonymization.
+  #
+  # Built on FindReplace for content rewriting plus a metadata strip
+  # pass for identifying attributes (rsids, author info, revision
+  # metadata, hidden text). Compliance use case Word cannot serve.
+  module Redact
+    autoload :Engine, "#{__dir__}/redact/engine"
+    autoload :Pattern, "#{__dir__}/redact/pattern"
+    autoload :PatternLibrary, "#{__dir__}/redact/pattern_library"
+    autoload :Result, "#{__dir__}/redact/result"
+  end
+end

data/lib/uniword/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Uniword
-  VERSION = "1.5.1"
+  VERSION = "1.5.3"
 end

data/lib/uniword/wordprocessingml/document_styling.rb

@@ -119,6 +119,122 @@ module Uniword
         replacer.replace(self)
       end
 
+      # Find and replace text across document parts.
+      #
+      # Mirrors Word's Home → Replace dialog (without the GUI).
+      # Replaces every non-overlapping match of `pattern` with
+      # `replacement` across the configured scopes. Returns a
+      # `FindReplace::Result` with per-scope counts.
+      #
+      # v1 limitation: matches inside a single run only. Matches
+      # that span run boundaries are silently skipped (Word does the
+      # same in default mode).
+      #
+      # @param pattern [String, Regexp] literal String or Regexp
+      # @param replacement [String] replacement text; for regex
+      #   patterns, may reference captures via `\1`, `\2`, ...
+      # @param scope [Symbol, Array<Symbol>, :all] one or more of
+      #   `:body`, `:headers`, `:footers`, `:footnotes`, `:endnotes`,
+      #   `:comments`, `:styles`, or `:all` (default)
+      # @param ignore_case [Boolean] case-insensitive match
+      # @return [FindReplace::Result]
+      def find_replace(pattern, replacement, scope: :all, ignore_case: false)
+        matcher = build_find_replace_matcher(pattern, replacement, ignore_case)
+        FindReplace::Engine.new(document: self, matcher: matcher,
+                                scopes: scope).run
+      end
+
+      # Turn change tracking on. Every subsequent edit is recorded as
+      # a tracked change. Mirrors Word's Review → Track Changes → On.
+      #
+      # @return [self]
+      def track_changes_on!
+        ensure_settings.track_changes = Wordprocessingml::TrackChanges.new
+        self
+      end
+
+      # Turn change tracking off. Existing tracked changes remain in
+      # the document; new edits are applied silently. Mirrors Word's
+      # Review → Track Changes → Off.
+      #
+      # @return [self]
+      def track_changes_off!
+        ensure_settings.track_changes = nil
+        self
+      end
+
+      # True when change tracking is enabled.
+      #
+      # @return [Boolean]
+      def track_changes_enabled?
+        settings&.track_changes ? true : false
+      end
+
+      # Redact PII patterns and/or custom regex across the document.
+      #
+      # Built on FindReplace. Default pattern library matches US
+      # phone numbers, email, SSN, credit card numbers, IPv4
+      # addresses. Pass `patterns: :pii` for defaults, or an array
+      # of names (`[:ssn, :email]`) to select a subset.
+      #
+      # @param patterns [Symbol, Array<Symbol>, Array<Redact::Pattern>]
+      #   `:pii` (default), or names/Pattern objects to apply
+      # @param scope [Symbol, Array<Symbol>, :all] find-replace scope
+      # @return [Redact::Result]
+      def redact(patterns: :pii, scope: :all)
+        Redact::Engine.new(document: self, patterns: patterns,
+                           scope: scope).run
+      end
+
+      # Run a lint ruleset against the document.
+      #
+      # @param ruleset [Lint::Ruleset, Array<Lint::Rule>] rules to
+      #   apply
+      # @return [Lint::Result]
+      def lint(ruleset:)
+        Lint::Engine.new(document: self, ruleset: ruleset).run
+      end
+
+      # Counter for auto-numbered captions. Persisted across the
+      # document's lifetime; reset on document load.
+      #
+      # @return [Caption::Counter]
+      def caption_counter
+        @caption_counter ||= Caption::Counter.new
+      end
+
+      # Add an auto-numbered caption paragraph to the body and
+      # return the bookmark name (for use in cross-references).
+      #
+      # The caption is appended as a new paragraph with style
+      # "Caption" and a SEQ field. The bookmark wraps the entire
+      # paragraph so cross-references resolve to the caption text.
+      #
+      # @param label [String] "Figure", "Table", "Equation", or any
+      #   other category — each gets its own counter
+      # @param text [String] caption body
+      # @param separator [String] between the label/number and the
+      #   body (default ": ")
+      # @return [String] bookmark name (e.g. "_Figure1")
+      def add_caption(label:, text:, separator: ": ")
+        builder = Caption::CaptionBuilder.new(caption_counter)
+        paragraph, bookmark_name = builder.build(label: label,
+                                                 text: text,
+                                                 separator: separator)
+        body.paragraphs << paragraph
+        bookmark_name
+      end
+
+      # Build a cross-reference run targeting a bookmark. Returns a
+      # Run containing a SimpleField with a REF instruction. The
+      # caller decides where to place it.
+      #
+      # @param bookmark_name [String] target bookmark
+      # @return [Wordprocessingml::SimpleField]
+      def cross_reference_to(bookmark_name)
+        Caption::CrossReference.new(bookmark_name).build
+      end
+
       # Apply uniform page setup to every section of the document
       #
       # Mirrors Word's Layout dialog: named paper sizes, orientation
@@ -230,6 +346,21 @@ module Uniword
 
       private
 
+      def build_find_replace_matcher(pattern, replacement, ignore_case)
+        if pattern.is_a?(Regexp)
+          FindReplace::RegexMatcher.new(pattern: pattern,
+                                        replacement: replacement)
+        else
+          FindReplace::StringMatcher.new(pattern: pattern,
+                                         replacement: replacement,
+                                         ignore_case: ignore_case)
+        end
+      end
+
+      def ensure_settings
+        self.settings ||= Wordprocessingml::Settings.new
+      end
+
       # Ensure the document carries a theme part, creating it from a
       # fresh parse of the bundled Office theme when absent (every
       # document gets its own copy — no shared state).

data/lib/uniword/wordprocessingml/settings.rb

@@ -37,6 +37,7 @@ module Uniword
       attribute :hyphenation_zone, HyphenationZone
       attribute :style_pane_sort_method, StylePaneSortMethod
       attribute :doc_vars, DocVars
+      attribute :track_changes, TrackChanges
       attribute :w14_doc_id, W14DocId
       attribute :w15_chart_tracking_ref_based, W15ChartTrackingRefBased
       attribute :w15_doc_id, W15DocId
@@ -106,6 +107,7 @@ module Uniword
         map_element "endnotePr", to: :endnote_pr, render_nil: false
         map_element "compat", to: :compat, render_nil: false
         map_element "docVars", to: :doc_vars, render_nil: false
+        map_element "trackChanges", to: :track_changes, render_nil: false
         map_element "rsids", to: :rsids, render_nil: false
         map_element "mathPr", to: :math_pr, render_nil: false
         map_element "themeFontLang", to: :theme_font_lang, render_nil: false

data/lib/uniword/wordprocessingml/track_changes.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Uniword
+  module Wordprocessingml
+    # Empty `<w:trackChanges/>` element in `<w:settings>` — Word's
+    # Review → Track Changes toggle.
+    #
+    # When present, Word records every edit as a tracked change. When
+    # absent, edits are applied silently.
+    class TrackChanges < Lutaml::Model::Serializable
+      xml do
+        element "trackChanges"
+        namespace Uniword::Ooxml::Namespaces::WordProcessingML
+      end
+    end
+  end
+end

data/lib/uniword/wordprocessingml.rb

@@ -88,6 +88,7 @@ module Uniword
     autoload :DefaultTabStop, "uniword/wordprocessingml/default_tab_stop"
     autoload :CharacterSpacingControl, "uniword/wordprocessingml/character_spacing_control"
     autoload :DoNotDisplayPageBoundaries, "uniword/wordprocessingml/do_not_display_page_boundaries"
+    autoload :TrackChanges, "uniword/wordprocessingml/track_changes"
     autoload :Rsids, "uniword/wordprocessingml/rsids"
     autoload :RsidRoot, "uniword/wordprocessingml/rsid_root"
     autoload :Rsid, "uniword/wordprocessingml/rsid"

data/lib/uniword.rb

@@ -130,6 +130,22 @@ module Uniword
   # Builder API (construction layer for OOXML models)
   autoload :Builder, "uniword/builder"
 
+  # Find & replace over document parts (body, headers, footers,
+  # footnotes, endnotes, comments, styles).
+  autoload :FindReplace, "uniword/find_replace"
+
+  # Document redaction (PII patterns, custom regex).
+  autoload :Redact, "uniword/redact"
+
+  # Document lint (style-guide enforcement).
+  autoload :Lint, "uniword/lint"
+
+  # Auto-numbered captions + cross-references.
+  autoload :Caption, "uniword/caption"
+
+  # Plugin system (validators, transformers, CLI commands).
+  autoload :Plugin, "uniword/plugin"
+
   # CLI
   autoload :CLI, "uniword/cli/main"
   autoload :GenerateCLI, "uniword/cli/generate_cli"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: uniword
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.5.3
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-27 00:00:00.000000000 Z
+date: 2026-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -592,6 +592,13 @@ files:
 - lib/uniword/batch.rb
 - lib/uniword/batch/batch_result.rb
 - lib/uniword/batch/document_processor.rb
+- lib/uniword/batch/operation.rb
+- lib/uniword/batch/operation/file_result.rb
+- lib/uniword/batch/operation/repair_task.rb
+- lib/uniword/batch/operation/report.rb
+- lib/uniword/batch/operation/runner.rb
+- lib/uniword/batch/operation/task.rb
+- lib/uniword/batch/operation/verify_task.rb
 - lib/uniword/batch/processing_stage.rb
 - lib/uniword/batch/stages/compress_images_stage.rb
 - lib/uniword/batch/stages/convert_format_stage.rb
@@ -656,6 +663,10 @@ files:
 - lib/uniword/builder/theme_builder.rb
 - lib/uniword/builder/toc_builder.rb
 - lib/uniword/builder/watermark_builder.rb
+- lib/uniword/caption.rb
+- lib/uniword/caption/caption_builder.rb
+- lib/uniword/caption/counter.rb
+- lib/uniword/caption/cross_reference.rb
 - lib/uniword/chart.rb
 - lib/uniword/chart/area3_d_chart.rb
 - lib/uniword/chart/area_chart.rb
@@ -800,6 +811,11 @@ files:
 - lib/uniword/diff/formatter.rb
 - lib/uniword/diff/package_diff_result.rb
 - lib/uniword/diff/package_differ.rb
+- lib/uniword/diff/semantic.rb
+- lib/uniword/diff/semantic/change.rb
+- lib/uniword/diff/semantic/engine.rb
+- lib/uniword/diff/semantic/paragraph_comparator.rb
+- lib/uniword/diff/semantic/result.rb
 - lib/uniword/document_factory.rb
 - lib/uniword/document_input.rb
 - lib/uniword/document_variables.rb
@@ -817,6 +833,7 @@ files:
 - lib/uniword/docx.rb
 - lib/uniword/docx/chart_part.rb
 - lib/uniword/docx/custom_xml_item.rb
+- lib/uniword/docx/deterministic_output.rb
 - lib/uniword/docx/document_statistics.rb
 - lib/uniword/docx/header_footer_part.rb
 - lib/uniword/docx/header_footer_part_collection.rb
@@ -1001,6 +1018,21 @@ files:
 - lib/uniword/endnote.rb
 - lib/uniword/errors.rb
 - lib/uniword/field.rb
+- lib/uniword/find_replace.rb
+- lib/uniword/find_replace/body_scope.rb
+- lib/uniword/find_replace/comment_scope.rb
+- lib/uniword/find_replace/endnote_scope.rb
+- lib/uniword/find_replace/engine.rb
+- lib/uniword/find_replace/footer_scope.rb
+- lib/uniword/find_replace/footnote_scope.rb
+- lib/uniword/find_replace/header_scope.rb
+- lib/uniword/find_replace/matcher.rb
+- lib/uniword/find_replace/paragraph_walker.rb
+- lib/uniword/find_replace/regex_matcher.rb
+- lib/uniword/find_replace/result.rb
+- lib/uniword/find_replace/scope.rb
+- lib/uniword/find_replace/string_matcher.rb
+- lib/uniword/find_replace/styles_scope.rb
 - lib/uniword/footer.rb
 - lib/uniword/footnote.rb
 - lib/uniword/format_converter.rb
@@ -1048,6 +1080,16 @@ files:
 - lib/uniword/infrastructure/zip_packager.rb
 - lib/uniword/lazy_loader.rb
 - lib/uniword/line_numbering.rb
+- lib/uniword/lint.rb
+- lib/uniword/lint/builtin_rules.rb
+- lib/uniword/lint/builtin_rules/banned_words.rb
+- lib/uniword/lint/builtin_rules/max_paragraph_length.rb
+- lib/uniword/lint/builtin_rules/require_body.rb
+- lib/uniword/lint/builtin_rules/required_style.rb
+- lib/uniword/lint/engine.rb
+- lib/uniword/lint/result.rb
+- lib/uniword/lint/rule.rb
+- lib/uniword/lint/ruleset.rb
 - lib/uniword/loggable.rb
 - lib/uniword/logger.rb
 - lib/uniword/math.rb
@@ -1179,6 +1221,12 @@ files:
 - lib/uniword/picture/picture_source_rect.rb
 - lib/uniword/picture/picture_stretch.rb
 - lib/uniword/picture/tile.rb
+- lib/uniword/plugin.rb
+- lib/uniword/plugin/cli_command.rb
+- lib/uniword/plugin/loader.rb
+- lib/uniword/plugin/registry.rb
+- lib/uniword/plugin/transformer.rb
+- lib/uniword/plugin/validator.rb
 - lib/uniword/presentationml.rb
 - lib/uniword/presentationml/audio.rb
 - lib/uniword/presentationml/body_properties.rb
@@ -1294,6 +1342,11 @@ files:
 - lib/uniword/quality/rules/paragraph_length_rule.rb
 - lib/uniword/quality/rules/style_consistency_rule.rb
 - lib/uniword/quality/rules/table_header_rule.rb
+- lib/uniword/redact.rb
+- lib/uniword/redact/engine.rb
+- lib/uniword/redact/pattern.rb
+- lib/uniword/redact/pattern_library.rb
+- lib/uniword/redact/result.rb
 - lib/uniword/resource.rb
 - lib/uniword/resource/cache.rb
 - lib/uniword/resource/cache_paths.rb
@@ -1849,6 +1902,7 @@ files:
 - lib/uniword/wordprocessingml/theme_font_lang.rb
 - lib/uniword/wordprocessingml/title_pg.rb
 - lib/uniword/wordprocessingml/tr_height.rb
+- lib/uniword/wordprocessingml/track_changes.rb
 - lib/uniword/wordprocessingml/ui_priority.rb
 - lib/uniword/wordprocessingml/update_fields.rb
 - lib/uniword/wordprocessingml/val_int.rb