uniword 1.5.1 → 1.5.3

data/lib/uniword/lint/builtin_rules/banned_words.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Uniword
+  module Lint
+    module BuiltinRules
+      # Rule: paragraphs containing banned words trigger a finding.
+      class BannedWords < Rule
+        register :banned_words, self
+
+        # @param words [Array<String>] words to flag
+        def initialize(words:, **rest)
+          super(**rest)
+          @banned = Set.new(Array(words).map(&:downcase))
+        end
+
+        def check(document)
+          document.paragraphs.each_with_index do |paragraph, idx|
+            text = paragraph.text.to_s.downcase
+            @banned.each do |word|
+              next unless text.match?(/\b#{Regexp.escape(word)}\b/)
+
+              yield finding(
+                message: "Paragraph #{idx + 1} contains banned word " \
+                         "'#{word}'",
+                path: "paragraph[#{idx}]",
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/lint/builtin_rules/max_paragraph_length.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Lint
+    module BuiltinRules
+      # Rule: paragraphs longer than `max` words trigger a finding.
+      class MaxParagraphLength < Rule
+        register :max_paragraph_length, self
+
+        # @param max [Integer] word count threshold (default 200)
+        def initialize(max: 200, **rest)
+          super(**rest)
+          @max = max
+        end
+
+        def check(document)
+          document.paragraphs.each_with_index do |paragraph, idx|
+            text = paragraph.text.to_s
+            word_count = text.split.length
+            next if word_count <= @max
+
+            yield finding(
+              message: "Paragraph #{idx + 1} has #{word_count} words " \
+                       "(max #{@max})",
+              path: "paragraph[#{idx}]",
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/lint/builtin_rules/require_body.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Lint
+    module BuiltinRules
+      # Rule: documents must have a non-empty body.
+      class RequireBody < Rule
+        register :require_body, self
+
+        def check(document)
+          body = document.body
+          paragraphs = body&.paragraphs || []
+          return if paragraphs.any?
+
+          yield finding(
+            message: "Document body is empty",
+            path: "word/document.xml",
+          )
+        end
+      end
+    end
+  end
+end

data/lib/uniword/lint/builtin_rules/required_style.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Lint
+    module BuiltinRules
+      # Rule: required style presence. Triggers when the named style
+      # is missing from the document.
+      class RequiredStyle < Rule
+        register :required_style, self
+
+        # @param style_id [String, Array<String>] required styleId(s)
+        def initialize(style_id:, **rest)
+          super(**rest)
+          @required = Array(style_id)
+        end
+
+        def check(document)
+          present = document.styles_configuration&.styles&.map(&:styleId) || []
+          @required.each do |id|
+            next if present.include?(id)
+
+            yield finding(
+              message: "Required style '#{id}' is missing",
+              path: "styles.xml",
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/lint/builtin_rules.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Lint
+    # Container module for builtin rule classes. Loaded eagerly by
+    # `Lint` so each class's `register` call fires.
+    module BuiltinRules
+      autoload :MaxParagraphLength,
+               "#{__dir__}/builtin_rules/max_paragraph_length"
+      autoload :BannedWords, "#{__dir__}/builtin_rules/banned_words"
+      autoload :RequiredStyle, "#{__dir__}/builtin_rules/required_style"
+      autoload :RequireBody, "#{__dir__}/builtin_rules/require_body"
+
+      # Touch every autoload to force-load + register each rule.
+      ALL = [
+        MaxParagraphLength,
+        BannedWords,
+        RequiredStyle,
+        RequireBody,
+      ].freeze
+    end
+  end
+end

data/lib/uniword/lint/engine.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Lint
+    # Walks the document with each rule and aggregates findings.
+    class Engine
+      # @param document [Wordprocessingml::DocumentRoot]
+      # @param ruleset [Ruleset, Array<Rule>] rules to apply
+      def initialize(document:, ruleset:)
+        @document = document
+        @ruleset = wrap_ruleset(ruleset)
+      end
+
+      # @return [Result]
+      def run
+        result = Result.new
+        @ruleset.rules.each do |rule|
+          rule.check(@document) { |finding| result.add(finding) }
+        end
+        result
+      end
+
+      private
+
+      def wrap_ruleset(ruleset)
+        return ruleset if ruleset.is_a?(Ruleset)
+
+        Ruleset.new(Array(ruleset))
+      end
+    end
+  end
+end

data/lib/uniword/lint/result.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Lint
+    # Aggregated lint result with severity counts.
+    class Result
+      SEVERITY_ORDER = %i[error warning info].freeze
+
+      attr_reader :findings
+
+      def initialize
+        @findings = []
+      end
+
+      # @param finding [Hash]
+      # @return [void]
+      def add(finding)
+        @findings << finding
+      end
+
+      # True when at least one :error severity finding exists.
+      #
+      # @return [Boolean]
+      def errors?
+        @findings.any? { |f| f[:severity] == :error }
+      end
+
+      # Count by severity.
+      #
+      # @return [Hash{Symbol => Integer}]
+      def by_severity
+        @findings.group_by { |f| f[:severity] }
+          .transform_values(&:count)
+      end
+
+      # Count by rule name.
+      #
+      # @return [Hash{Symbol => Integer}]
+      def by_rule
+        @findings.group_by { |f| f[:rule] }
+          .transform_values(&:count)
+      end
+
+      # Total finding count.
+      #
+      # @return [Integer]
+      def count
+        @findings.length
+      end
+
+      # True when zero findings.
+      #
+      # @return [Boolean]
+      def empty?
+        @findings.empty?
+      end
+    end
+  end
+end

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/plugin/cli_command.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Plugin
+    # Base class for plugin-provided CLI commands. A plugin CLI
+    # command is a Thor subclass that the main CLI registers as a
+    # subcommand.
+    #
+    # Subclasses declare `subcommand_name` (the name CLI users type)
+    # and `description` (shown in `uniword help`).
+    class CliCommand
+      class << self
+        # @return [Symbol] subcommand name (e.g. :myplugin)
+        def subcommand_name
+          raise NotImplementedError
+        end
+
+        # @return [String] one-line description
+        def description
+          raise NotImplementedError
+        end
+
+        # @return [Class<Thor>] the Thor subclass to register
+        def thor_class
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/uniword/plugin/loader.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Plugin
+    # Discovers plugins from installed gems. Each plugin ships a
+    # ruby file under `uniword/plugin/<name>.rb` that registers
+    # itself with `Plugin::Registry` on load.
+    class Loader
+      GLOB = "uniword/plugin/*.rb"
+
+      class << self
+        # Load every plugin file found in installed gems.
+        #
+        # @return [Array<String>] paths loaded
+        def load_all
+          Gem.find_files(GLOB).each { |path| require path }
+        end
+
+        # Run every registered transformer whose `stages` include
+        # `stage`, in registration order.
+        #
+        # @param document [Wordprocessingml::DocumentRoot]
+        # @param stage [Symbol] one of `Transformer::STAGES`
+        # @return [void]
+        def run_transformers(document:, stage:)
+          Registry.transformers.each_value do |transformer|
+            next unless transformer.applies_to?(stage)
+
+            transformer.transform(document)
+          end
+        end
+
+        # Yield every registered validator in registration order.
+        #
+        # @yieldparam validator [Plugin::Validator]
+        # @return [void]
+        def each_validator(&block)
+          Registry.validators.each_value(&block)
+        end
+      end
+    end
+  end
+end

data/lib/uniword/plugin/registry.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Plugin
+    # Central registry for installed plugins. Each plugin registers
+    # its extension surface (validator, transformer, cli command) by
+    # name; lookup is by name or by class.
+    #
+    # Open/closed: new extension surfaces = new methods on this
+    # class. Existing entries untouched.
+    class Registry
+      @validators = {}
+      @transformers = {}
+      @cli_commands = {}
+
+      class << self
+        # @return [Hash{Symbol => Plugin::Validator}]
+        attr_reader :validators
+
+        # @return [Hash{Symbol => Plugin::Transformer}]
+        attr_reader :transformers
+
+        # @return [Hash{Symbol => Plugin::CliCommand}]
+        attr_reader :cli_commands
+
+        # Register a validator. Append-only; duplicate name raises.
+        #
+        # @param name [Symbol]
+        # @param validator [Plugin::Validator]
+        # @return [void]
+        def register_validator(name, validator)
+          raise ArgumentError, "name must be a Symbol" unless name.is_a?(Symbol)
+          unless validator.is_a?(Validator)
+            raise ArgumentError,
+                  "validator must be a Validator"
+          end
+
+          @validators[name] = validator
+        end
+
+        # Register a transformer.
+        #
+        # @param name [Symbol]
+        # @param transformer [Plugin::Transformer]
+        # @return [void]
+        def register_transformer(name, transformer)
+          raise ArgumentError, "name must be a Symbol" unless name.is_a?(Symbol)
+          unless transformer.is_a?(Transformer)
+            raise ArgumentError,
+                  "transformer must be a Transformer"
+          end
+
+          @transformers[name] = transformer
+        end
+
+        # Register a CLI command (a Thor subclass).
+        #
+        # @param name [Symbol]
+        # @param command_class [Class]
+        # @return [void]
+        def register_cli_command(name, command_class)
+          raise ArgumentError, "name must be a Symbol" unless name.is_a?(Symbol)
+          unless command_class.is_a?(Class)
+            raise ArgumentError,
+                  "command_class must be a Class"
+          end
+
+          @cli_commands[name] = command_class
+        end
+
+        # Clear every registry. Used between tests and by
+        # `Configuration#reset!`.
+        #
+        # @return [void]
+        def clear
+          @validators.clear
+          @transformers.clear
+          @cli_commands.clear
+        end
+      end
+    end
+  end
+end

data/lib/uniword/plugin/transformer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Plugin
+    # Base class for plugin-provided document transformers.
+    # Subclasses implement `#transform(document)` which mutates the
+    # document in place.
+    #
+    # Pipelines call transformers at defined stages; see
+    # `Plugin.transform_for_stage`.
+    class Transformer
+      STAGES = %i[after_load before_save after_reconcile].freeze
+
+      # @return [Symbol] transformer name
+      attr_reader :name
+
+      # @return [Array<Symbol>] stages when this transformer runs
+      attr_reader :stages
+
+      # @param name [Symbol]
+      # @param stages [Array<Symbol>, Symbol] one or more of
+      #   STAGES; defaults to `:before_save`
+      def initialize(name:, stages: :before_save)
+        @name = name
+        @stages = Array(stages)
+        unknown = @stages - STAGES
+        return if unknown.empty?
+
+        raise ArgumentError,
+              "unknown stages: #{unknown.inspect}; valid: #{STAGES.inspect}"
+      end
+
+      # True when this transformer runs at the given stage.
+      #
+      # @param stage [Symbol]
+      # @return [Boolean]
+      def applies_to?(stage)
+        @stages.include?(stage)
+      end
+
+      # Mutate the document. Subclasses override.
+      #
+      # @param document [Wordprocessingml::DocumentRoot]
+      # @return [void]
+      def transform(document)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/uniword/plugin/validator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Plugin
+    # Base class for plugin-provided validation rules. Subclasses
+    # implement `#check(document)` (yields findings).
+    #
+    # Open/closed: adding a new validator = subclassing + calling
+    # `Registry.register_validator`.
+    class Validator
+      # @return [Symbol] validator name (matches the registry key)
+      attr_reader :name
+
+      # @return [Symbol] default severity (:error, :warning, :info)
+      attr_reader :severity
+
+      # @param name [Symbol]
+      # @param severity [Symbol]
+      def initialize(name:, severity: :warning)
+        @name = name
+        @severity = severity
+      end
+
+      # Walk the document and yield each finding as a hash.
+      #
+      # @param document [Wordprocessingml::DocumentRoot]
+      # @yieldparam finding [Hash] { message:, path: }
+      # @return [void]
+      def check(document)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/uniword/plugin.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Uniword
+  # Plugin system: extend uniword without forking.
+  #
+  # Three extension surfaces, each with a base class:
+  #
+  # - `Plugin::Validator` — register custom validation rules
+  # - `Plugin::Transformer` — mutate documents at defined pipeline
+  #   stages (load, pre-save, post-reconcile)
+  # - `Plugin::CliCommand` — register new Thor subcommands
+  #
+  # Discovery: `Plugin::Loader.load_all` walks installed gems via
+  # `Gem.find_files("uniword/plugin/*.rb")` and loads each.
+  #
+  # Configuration: `Uniword.configuration.plugins = [:my_plugin]`
+  # (default `:all`).
+  module Plugin
+    autoload :Registry, "#{__dir__}/plugin/registry"
+    autoload :Validator, "#{__dir__}/plugin/validator"
+    autoload :Transformer, "#{__dir__}/plugin/transformer"
+    autoload :CliCommand, "#{__dir__}/plugin/cli_command"
+    autoload :Loader, "#{__dir__}/plugin/loader"
+  end
+end