uniword 1.5.0 → 1.5.2

data/lib/uniword/lint/rule.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Lint
+    # Abstract base class for a single lint rule. Subclasses implement
+    # `#check` (yields findings) and declare `name`, `severity`.
+    #
+    # Open/closed: new rule type = new subclass + (optionally) a
+    # YAML schema extension. Engine unchanged.
+    class Rule
+      # Registered rule subclasses by type name. Constant on `Rule`
+      # itself (not subclasses) so `register` calls always reach the
+      # same hash. `Hash.new` (rather than `{}`) avoids the
+      # Style/MutableConstant autocorrect that would `.freeze` it and
+      # break `register`.
+      TYPES = Hash.new
+
+      attr_reader :name, :severity, :options
+
+      # @param name [Symbol] rule identifier
+      # @param severity [Symbol] :error, :warning, or :info
+      # @param options [Hash] rule-specific options
+      def initialize(name:, severity: :warning, **options)
+        @name = name
+        @severity = severity
+        @options = options
+      end
+
+      # Walk the document and yield each finding.
+      #
+      # @param document [Wordprocessingml::DocumentRoot]
+      # @yieldparam finding [Hash] { message:, path:, position: }
+      # @return [void]
+      def check(document)
+        raise NotImplementedError
+      end
+
+      # Build a finding hash.
+      #
+      # @param message [String]
+      # @param path [String, nil] document path (paragraph index,
+      #   style id, etc.)
+      # @return [Hash]
+      def finding(message:, path: nil)
+        { rule: name, severity: severity, message: message, path: path }
+      end
+
+      class << self
+        # Register a subclass under a type name for YAML ruleset
+        # lookup. Always writes to `Rule::TYPES` regardless of the
+        # calling subclass.
+        #
+        # @param name [Symbol]
+        # @param klass [Class<Rule>]
+        # @return [void]
+        def register(name, klass)
+          Rule::TYPES[name] = klass
+        end
+
+        # Lookup a registered rule subclass by type name.
+        #
+        # @param name [Symbol]
+        # @return [Class<Rule>, nil]
+        def type(name)
+          Rule::TYPES[name]
+        end
+
+        # All registered rule types.
+        #
+        # @return [Hash{Symbol => Class<Rule>}]
+        def types
+          Rule::TYPES
+        end
+      end
+    end
+  end
+end

data/lib/uniword/lint/ruleset.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Uniword
+  module Lint
+    # Loads rules from a YAML ruleset or symbol registry. Each rule
+    # has a `type` (which `Rule` subclass to instantiate) and
+    # rule-specific options.
+    #
+    # Example YAML:
+    #
+    #   rules:
+    #     - type: sentence_case_headings
+    #       severity: warning
+    #     - type: max_paragraph_length
+    #       severity: warning
+    #       max: 200
+    #     - type: banned_words
+    #       severity: warning
+    #       words: [really, very, basically]
+    class Ruleset
+      # @param rules [Array<Rule>]
+      def initialize(rules = [])
+        @rules = rules
+      end
+
+      # @return [Array<Rule>]
+      attr_reader :rules
+
+      # Load a ruleset from a YAML file.
+      #
+      # @param path [String]
+      # @return [Ruleset]
+      def self.load(path)
+        data = YAML.safe_load_file(path)
+        from_hash(data || {})
+      end
+
+      # Build a ruleset from a parsed YAML hash.
+      #
+      # @param data [Hash] `{"rules" => [{"type" => ..., ...}, ...]}`
+      # @return [Ruleset]
+      def self.from_hash(data)
+        rule_list = (data["rules"] || []).map { |spec| build_rule(spec) }
+        new(rule_list)
+      end
+
+      # Build one rule from a spec hash by type name.
+      #
+      # @param spec [Hash] `{"type" => "name", "severity" => ...}`
+      # @return [Rule]
+      def self.build_rule(spec)
+        type = spec["type"].to_sym
+        klass = Rule.types[type]
+        raise ArgumentError, "unknown rule type: #{spec['type']}" unless klass
+
+        kwargs = spec.transform_keys(&:to_sym)
+        kwargs.delete(:type)
+        kwargs[:name] = type unless kwargs.key?(:name)
+        klass.new(**kwargs)
+      end
+    end
+  end
+end

data/lib/uniword/lint.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Uniword
+  # Document lint: enforce content + structure rules beyond OPC
+  # validity. Backed by a YAML ruleset; rules are open for extension
+  # via `Lint::Rule.register`.
+  module Lint
+    autoload :Engine, "#{__dir__}/lint/engine"
+    autoload :Ruleset, "#{__dir__}/lint/ruleset"
+    autoload :Rule, "#{__dir__}/lint/rule"
+    autoload :Result, "#{__dir__}/lint/result"
+    autoload :BuiltinRules, "#{__dir__}/lint/builtin_rules"
+
+    # Force-load the builtins so their `register` calls run.
+    BuiltinRules.to_s
+  end
+end

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.0"
+  VERSION = "1.5.2"
 end

data/lib/uniword/wordprocessingml/document_styling.rb

@@ -119,6 +119,82 @@ 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
+
       # Apply uniform page setup to every section of the document
       #
       # Mirrors Word's Layout dialog: named paper sizes, orientation
@@ -230,6 +306,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,16 @@ 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"
+
   # 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.0
+  version: 1.5.2
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-21 00:00:00.000000000 Z
+date: 2026-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -817,6 +817,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 +1002,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 +1064,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
@@ -1294,6 +1320,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 +1880,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