swear_jar 0.1.0

data/lib/swear_jar/pattern_builder.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module SwearJar
+  # Compiles a word list into one detection regexp (generated from a trie of stem runs),
+  # per-spelling anchored regexps for entry identification, and an allowlist regexp.
+  #
+  # @api private
+  class PatternBuilder
+    LEET = {
+      'a' => 'a4@', 'o' => 'o0', 'i' => 'i1!|', 'e' => 'e3', 's' => 's$5',
+      't' => 't7', 'l' => 'l1|', 'b' => 'b8', 'g' => 'g9'
+    }.freeze
+    CLASS_SPECIALS = ['-', ']', '[', '\\', '^'].freeze
+    # Leet symbols. They are not word characters for LEFT, so a word may start after them.
+    SYMBOLS = '!|@$'
+    LEFT = '(?<![\p{L}\p{N}*])'
+    RIGHT = '(?![\p{L}\p{N}*])'
+    JOIN = '[.\-~]*'
+    GAP = '[.\-~ ]*'
+    NEVER = /(?!)/
+    LETTER = /\p{L}/
+    DIGIT = /\p{N}/
+    PREFIXED_LOCALES = %i[pl].freeze
+    # Trie token for a run of non-letters inside a stem (e.g. the space in a multi-word entry).
+    GAP_TOKEN = :gap
+    TERMINAL = :end
+
+    attr_reader :mode, :scanner, :entry_patterns, :allow_pattern, :prefixes
+
+    # +entry_patterns+: [entry, anchored (`\G`) regexp of the stem, characters the stem can start
+    # with], one per folded spelling. A stem regexp has no prefixes: the matcher tries them.
+    # +prefixes+: locale => folded prefixes, longest first (empty for unprefixed locales).
+    # +allow_pattern+: the allowlist regexp, or nil.
+    def initialize(word_list, mode:)
+      raise ArgumentError, "unknown mode #{mode.inspect}, expected #{MODES.inspect}" unless MODES.include?(mode)
+
+      @mode = mode
+      @prefixes = folded_prefixes(word_list.prefixes)
+      spellings = word_list.entries.map { |entry| [entry, spelling_tokens(entry)] }
+      @scanner = build_scanner(spellings, mode)
+      @entry_patterns = build_entry_patterns(spellings)
+      @allow_pattern = build_allow_pattern(word_list)
+      freeze
+    end
+
+    def inspect
+      "#<#{self.class.name} mode=#{mode.inspect} entries=#{entry_patterns.map(&:first).uniq.size}>"
+    end
+
+    private
+
+    def spelling_tokens(entry)
+      where = "#{entry.source}: entry #{entry.stem.inspect}"
+      entry.spellings.map { |spelling| tokens(spelling, where) }.uniq
+    end
+
+    # Folds +word+ and splits it into runs of identical letters, [letter, count, final], with
+    # GAP_TOKEN standing for any run of non-letters between them. Only the last run is final.
+    def tokens(word, where)
+      list = []
+      Normalizer.fold(word).each_char do |char|
+        raise InvalidWordListError, "#{where}: #{word.inspect} contains a digit" if DIGIT.match?(char)
+
+        if !LETTER.match?(char)
+          list << GAP_TOKEN unless list.empty? || list.last == GAP_TOKEN
+        elsif list.last.is_a?(Array) && list.last[0] == char
+          list[-1] = [char, list.last[1] + 1, false]
+        else
+          list << [char, 1, false]
+        end
+      end
+      list.pop if list.last == GAP_TOKEN
+      raise InvalidWordListError, "#{where}: #{word.inspect} has no letters" if list.empty?
+
+      list[-1] = [*list.last.take(2), true]
+      list
+    end
+
+    def build_scanner(spellings, mode)
+      exact, loose = spellings.partition { |entry, _| entry.exact }
+      bounded, free = loose.partition { |entry, _| mode == :words || !entry.embeddable }
+      bounded_parts = LOCALES.filter_map { |locale| locale_branch(bounded, locale, guard: :symbols) }
+      exact_trie = render_trie(exact.flat_map(&:last), guard: :symbols)
+      bounded_parts << "#{exact_trie}#{RIGHT}" if exact_trie
+      free_parts = LOCALES.filter_map { |locale| locale_branch(free, locale, guard: :run, prefixed: false) }
+
+      parts = []
+      parts << "#{LEFT}(?:#{bounded_parts.join('|')})" unless bounded_parts.empty?
+      parts << "(?:#{free_parts.join('|')})" unless free_parts.empty?
+      parts.empty? ? NEVER : Regexp.new(parts.join('|'))
+    end
+
+    def locale_branch(spellings, locale, guard:, prefixed: true)
+      trie = render_trie(spellings.select { |entry, _| entry.locale == locale }.flat_map(&:last), guard: guard)
+      return unless trie
+
+      prefixed ? "#{prefix_group(locale)}#{trie}" : trie
+    end
+
+    # Folded prefixes per locale, longest first. Only PREFIXED_LOCALES have any.
+    def folded_prefixes(prefixes)
+      LOCALES.to_h do |locale|
+        list = PREFIXED_LOCALES.include?(locale) ? Array(prefixes[locale]) : []
+        folded = list.map { |p| Normalizer.fold(p) }.reject(&:empty?).uniq
+        [locale, folded.sort_by.with_index { |p, i| [-p.length, i] }.freeze]
+      end.freeze
+    end
+
+    def prefix_group(locale)
+      list = @prefixes[locale]
+      list.empty? ? '' : "(?:#{list.map { |p| Regexp.escape(p) }.join('|')})?"
+    end
+
+    def build_entry_patterns(spellings)
+      spellings.flat_map do |entry, token_lists|
+        suffix = entry.exact ? RIGHT : ''
+        token_lists.map do |list|
+          # The first run is never masked, so a stem starts with a character of its class.
+          first_chars = (LEET[list.first[0]] || list.first[0]).chars.freeze
+          [entry, Regexp.new("\\G#{render_trie([list])}#{suffix}"), first_chars].freeze
+        end
+      end.freeze
+    end
+
+    def build_allow_pattern(word_list)
+      sources = word_list.allow_sources
+      lists = word_list.allow.map { |word| tokens(word, "#{sources.fetch(word, 'allow')}: allow word") }
+      trie = render_trie(lists, guard: :run)
+      trie && Regexp.new("\\G#{trie}")
+    end
+
+    # Builds a trie (nested Hashes keyed by token, TERMINAL marks an end) and renders it.
+    # Final runs are distinct tokens, so a node is either terminal or has children, never both.
+    # +guard+ adds a lookbehind to each root run, so a pattern searched without an anchor
+    # cannot start inside a run and rescan it (quadratic without regexp memoization):
+    # :run rejects any character of the run's class before it; :symbols rejects two leet
+    # symbols of the class (for branches behind LEFT, which a single symbol does not stop:
+    # `hello!idiot` must still match).
+    def render_trie(token_lists, guard: nil)
+      root = {}
+      token_lists.each do |list|
+        node = list.reduce(root) { |current, token| current[token] ||= {} }
+        node[TERMINAL] = true
+      end
+      render_children(root, nil, guard)
+    end
+
+    # Renders the alternatives below +node+, whose own token is +parent+ (nil at the root).
+    # Non-final runs come first so the longer spellings are tried first.
+    # Returns nil when the node has no children.
+    def render_children(node, parent, guard = nil)
+      children = node.reject { |token, _| token == TERMINAL }
+      children = children.sort_by.with_index { |(token, _), i| [final?(token) ? 1 : 0, i] }
+      branches = children.map do |token, child|
+        [lead(parent, token), "#{atom(token, parent.nil?, guard)}#{render_children(child, token)}"]
+      end
+      return if branches.empty?
+
+      leads = branches.map(&:first).uniq
+      return "#{leads.first}#{group(branches.map(&:last))}" if leads.size == 1
+
+      group(branches.map { |head, body| "#{head}#{body}" })
+    end
+
+    def final?(token)
+      token.is_a?(Array) && token[2]
+    end
+
+    def group(alternatives)
+      alternatives.size == 1 ? alternatives.first : "(?:#{alternatives.join('|')})"
+    end
+
+    def lead(parent, token)
+      parent.nil? || parent == GAP_TOKEN || token == GAP_TOKEN ? '' : JOIN
+    end
+
+    # A run is atomic and greedy. Note: when adjacent runs have overlapping leet classes
+    # (i `[i1!|]` and l `[l1|]`), the first run swallows the shared symbols and the match fails.
+    # Masks may replace only interior runs, never the first or the last one, and stand for
+    # up to as many letters as the run has (`a**hole`).
+    def atom(token, first, guard)
+      return GAP if token == GAP_TOKEN
+
+      letter, count, final = token
+      klass = letter_class(letter)
+      return guarded_run(letter, klass, count, guard) if first
+
+      run = "(?>#{klass}#{count == 1 ? '+' : "{#{count},}"})"
+      return run if final
+
+      masks = count == 1 ? '\\*' : "\\*{1,#{count}}"
+      "(?:#{run}|#{masks})"
+    end
+
+    # The guard looks behind the first character of the run rather than before it, so it only
+    # runs where that character already matched: the many branches of the scanner tried at
+    # every word start stay cheap.
+    def guarded_run(letter, klass, count, guard)
+      rest = count == 1 ? '*' : "{#{count - 1},}"
+      "(?>#{klass}#{guard_behind(letter, klass, guard)}#{klass}#{rest})"
+    end
+
+    def guard_behind(letter, klass, guard)
+      case guard
+      when :run then "(?<!#{klass}{2})"
+      when :symbols
+        symbols = (LEET[letter] || letter).delete("^#{SYMBOLS}")
+        symbols.empty? ? '' : "(?<!#{class_of(symbols.chars)}{2}#{klass})"
+      else ''
+      end
+    end
+
+    def letter_class(letter)
+      class_of((LEET[letter] || letter).chars.uniq)
+    end
+
+    def class_of(chars)
+      "[#{chars.map { |c| CLASS_SPECIALS.include?(c) ? "\\#{c}" : c }.join}]"
+    end
+  end
+end

data/lib/swear_jar/railtie.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module SwearJar
+  class Railtie < Rails::Railtie
+    config.swear_jar = ActiveSupport::OrderedOptions.new
+
+    # Unknown keys raise ArgumentError.
+    def self.apply_config(options)
+      return if options.empty?
+
+      options.each_key do |key|
+        raise ArgumentError, "unknown config.swear_jar option: #{key.inspect}" unless Configuration::DEFAULTS.key?(key.to_sym)
+      end
+
+      SwearJar.configure do |configuration|
+        options.each { |key, value| configuration.public_send(:"#{key}=", value) }
+      end
+    end
+
+    # Builds the global detector at boot rather than on first use, so app servers that preload
+    # the app (Puma preload_app!) share it between workers through copy-on-write.
+    initializer 'swear_jar.configure', after: :load_config_initializers do |app|
+      Railtie.apply_config(app.config.swear_jar)
+      SwearJar.detector
+    end
+
+    initializer 'swear_jar.validator' do
+      require 'swear_jar/swear_jar_validator'
+    rescue LoadError => e
+      # railties does not depend on activemodel; only skip when that is what is missing.
+      raise unless e.path == 'active_model'
+    end
+  end
+end

data/lib/swear_jar/skeleton.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'strscan'
+
+module SwearJar
+  # Read access to one skeleton by character index, in constant time per call. Ruby indexes a
+  # non-ASCII string by scanning it from the start, so a message with many hits would cost
+  # O(length) per hit; here a non-ASCII skeleton gets a character <=> byte offset table once
+  # and all matching goes through a StringScanner at byte positions. Anchored matching also
+  # needs StringScanner: Regexp#match(string, pos) with `\G` is not reliably anchored, since for
+  # a pattern with a required substring (`{2,}` runs) Onigmo first searches the rest of the
+  # string for it. fixed_anchor lets lookbehinds see before the position.
+  #
+  # @api private
+  class Skeleton
+    NON_WORD = /[^\p{L}\p{N}*@$!|]/
+
+    attr_reader :string, :length
+
+    def initialize(string)
+      @string = string
+      @length = string.length
+      @scanner = StringScanner.new(string, fixed_anchor: true)
+      build_offsets unless string.ascii_only?
+    end
+
+    def [](index)
+      return @string[index] unless @offsets
+      return if index >= @length
+
+      @string.byteslice(@offsets[index], @offsets[index + 1] - @offsets[index])
+    end
+
+    def slice(first, last)
+      return @string[first...last] unless @offsets
+
+      @string.byteslice(@offsets[first], @offsets[last] - @offsets[first])
+    end
+
+    # The end of a +pattern+ match starting exactly at +at+, or nil.
+    def match(pattern, at)
+      @scanner.pos = byte(at)
+      @scanner.skip(pattern) && char(@scanner.pos)
+    end
+
+    def literal?(string, at)
+      @scanner.pos = byte(at)
+      !@scanner.skip(string).nil?
+    end
+
+    # [begin, end] of the first +pattern+ match at or after +from+, or nil.
+    def search(pattern, from)
+      @scanner.pos = byte(from)
+      return unless @scanner.skip_until(pattern)
+
+      [char(@scanner.pos - @scanner.matched_size), char(@scanner.pos)]
+    end
+
+    def word_start(pos)
+      return 0 if pos.zero?
+
+      unless @offsets
+        boundary = @string.rindex(NON_WORD, pos - 1)
+        return boundary ? boundary + 1 : 0
+      end
+      index = breaks.bsearch_index { |at| at >= pos } || breaks.size
+      index.zero? ? 0 : breaks[index - 1] + 1
+    end
+
+    # The end of the word that contains +pos+ (or +pos+ itself when it is not in a word).
+    def word_end(pos)
+      return @string.index(NON_WORD, pos) || @length unless @offsets
+
+      breaks.bsearch { |at| at >= pos } || @length
+    end
+
+    def inspect
+      "#<#{self.class.name} length=#{@length}>"
+    end
+
+    private
+
+    def byte(char)
+      @offsets ? @offsets[char] : char
+    end
+
+    def char(byte)
+      @chars ? @chars[byte] : byte
+    end
+
+    # @offsets: character index => byte offset (plus the total size at the end);
+    # @chars: byte offset of a character => its index.
+    def build_offsets
+      @offsets = []
+      @chars = []
+      offset = 0
+      @string.each_char.with_index do |character, index|
+        @offsets << offset
+        @chars[offset] = index
+        offset += character.bytesize
+      end
+      @offsets << offset
+      @chars[offset] = @length
+    end
+
+    # Sorted indexes of the non-word characters, built on first use.
+    def breaks
+      @breaks ||= begin
+        list = []
+        @scanner.pos = 0
+        list << char(@scanner.pos - @scanner.matched_size) while @scanner.skip_until(NON_WORD)
+        list
+      end
+    end
+  end
+end

data/lib/swear_jar/slicer.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module SwearJar
+  # Cuts match texts out of the original string. Indexing a long non-ASCII string by
+  # characters, or slicing a long piece of it, scans it from the start, so slicing each of many
+  # matches in a long message would cost O(length) per match. Matches come in order, so a
+  # cursor (character and byte offset) moves forward instead, and each slice works on a short
+  # byte window, costing only the distance from the previous match.
+  #
+  # @api private
+  class Slicer
+    # Combining marks right after a match belong to its last character.
+    TRAILING_MARKS = /\G\p{M}+/
+    # A UTF-8 character takes at most 4 bytes; extra room for the marks after a match.
+    CHAR_BYTES = 4
+    MARKS_ROOM = 64
+
+    def initialize(string)
+      @string = string
+      @char = 0
+      @byte = 0
+    end
+
+    # [range, text] for the characters from +first+ to +last+ (exclusive), extended over the
+    # combining marks that follow. +first+ must not be before the previous call's +first+.
+    def slice(first, last)
+      skip_to(first)
+      length = last - first
+      room = (CHAR_BYTES * length) + MARKS_ROOM
+      loop do
+        window = window(room)
+        marks = TRAILING_MARKS.match(window, length)
+        if marks.nil? || marks.end(0) < window.length || @byte + room >= @string.bytesize
+          length = marks.end(0) if marks
+          return [first...(first + length), window[0, length]]
+        end
+        room *= 2
+      end
+    end
+
+    def inspect
+      "#<#{self.class.name} at=#{@char}>"
+    end
+
+    private
+
+    def skip_to(first)
+      distance = first - @char
+      @byte += window(CHAR_BYTES * distance)[0, distance].bytesize
+      @char = first
+    end
+
+    # Up to +bytes+ bytes from the cursor, without a character cut off at the end.
+    def window(bytes)
+      @string.byteslice(@byte, bytes).scrub('')
+    end
+  end
+end

data/lib/swear_jar/swear_jar_validator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'swear_jar'
+require 'active_model'
+require 'i18n'
+
+I18n.load_path |= Dir[File.join(SwearJar::ROOT_PATH, 'config', 'locales', '*.yml')]
+
+# Validates that an attribute contains no profanity. Without detector options it uses
+# +SwearJar.detector+; otherwise it uses a detector cached per option set.
+class SwearJarValidator < ActiveModel::EachValidator
+  STANDARD_OPTIONS = %i[message if unless on allow_nil allow_blank strict].freeze
+
+  @detectors = {}
+  @mutex = Mutex.new
+
+  class << self
+    def detector_for(detector_options)
+      key = detector_options.sort_by { |name, _| name.to_s }.to_h { |name, value| [name, freeze_value(value)] }.freeze
+      @detectors[key] || @mutex.synchronize { @detectors[key] ||= SwearJar::Detector.new(**key) }
+    end
+  end
+
+  def self.freeze_value(value)
+    value.is_a?(Array) ? value.map { |item| freeze_value(item) }.freeze : value.dup.freeze
+  end
+  private_class_method :freeze_value
+
+  def validate_each(record, attribute, value)
+    return if value.blank?
+
+    # A custom message replaces only the text: the error type stays :profane.
+    record.errors.add(attribute, :profane, **options.slice(:message)) if detector.profane?(value.to_s)
+  end
+
+  private
+
+  def detector
+    detector_options = options.except(*STANDARD_OPTIONS)
+    return SwearJar.detector if detector_options.empty?
+
+    self.class.detector_for(detector_options)
+  end
+end

data/lib/swear_jar/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SwearJar
+  VERSION = '0.1.0'
+end

data/lib/swear_jar/word_list.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module SwearJar
+  # @api private
+  class WordList
+    FILE_KEYS = %w[locale prefixes words allow].freeze
+    EXTRA_SOURCE = 'extra_words'
+    ALLOW_SOURCE = 'allow option'
+    GLOB_CHARS = /[*?\[{]/
+
+    # +allow_sources+: each allow word => where it came from, for error messages.
+    attr_reader :locales, :entries, :prefixes, :allow, :allow_sources
+
+    def self.load(locales: LOCALES, min_severity: :mild, categories: nil, extra_paths: [], extra_words: [], allow: [])
+      locales = validated_option(:locales, symbolize(Array(locales)), LOCALES)
+      min_severity = validated_option(:min_severity, symbolize([min_severity]), SEVERITIES).first
+      categories = validated_option(:categories, symbolize(Array(categories)), CATEGORIES) if categories
+      new(locales: locales, min_severity: min_severity, categories: categories,
+          extra_paths: extra_paths, extra_words: extra_words, allow: allow)
+    end
+
+    # An empty list is rejected too: it would build a detector that silently finds nothing.
+    def self.validated_option(name, values, allowed)
+      raise ArgumentError, "#{name} must not be empty, expected some of #{allowed.inspect}" if values.empty?
+
+      unknown = values - allowed
+      return values if unknown.empty?
+
+      raise ArgumentError, "unknown #{name} #{unknown.inspect}, expected #{allowed.inspect}"
+    end
+
+    def self.symbolize(values)
+      values.map { |v| v.respond_to?(:to_sym) ? v.to_sym : v }
+    end
+    private_class_method :validated_option, :symbolize
+
+    def initialize(locales:, min_severity:, categories:, extra_paths:, extra_words:, allow:)
+      @locales = locales.freeze
+      sources = bundled_sources(locales) + extra_sources(extra_paths, locales) + extra_word_sources(extra_words)
+      min_rank = SEVERITIES.index(min_severity)
+      @entries = sources.flat_map { |s| s[:entries] }.select { |e| keep?(e, locales, min_rank, categories) }.freeze
+      @prefixes = collect_prefixes(sources, locales)
+      @allow_sources = collect_allow(sources, allow)
+      @allow = @allow_sources.keys.freeze
+      freeze
+    end
+
+    def inspect
+      "#<#{self.class.name} entries=#{entries.size} allow=#{allow.size}>"
+    end
+
+    private
+
+    def keep?(entry, locales, min_rank, categories)
+      locales.include?(entry.locale) && entry.rank >= min_rank &&
+        (categories.nil? || (categories & entry.categories).any?)
+    end
+
+    def collect_prefixes(sources, locales)
+      locales.to_h do |locale|
+        list = sources.select { |s| s[:locale] == locale }.flat_map { |s| s[:prefixes] }.uniq
+        [locale, list.sort_by.with_index { |p, i| [-p.length, i] }.freeze]
+      end.freeze
+    end
+
+    # Allow words in order, without duplicates => the source of their first occurrence.
+    def collect_allow(sources, allow)
+      pairs = sources.flat_map { |s| s[:allow].map { |word| [word, s[:path]] } }
+      pairs += Array(allow).map { |word| [word.to_s.dup.freeze, ALLOW_SOURCE] }
+      pairs.each_with_object({}) { |(word, source), all| all[word] ||= source }.freeze
+    end
+
+    def bundled_sources(locales)
+      locales.map { |locale| read_file(File.join(ROOT_PATH, 'locales', locale.to_s, 'words.yml'), locale) }
+    end
+
+    def extra_sources(extra_paths, locales)
+      Array(extra_paths).flat_map { |pattern| extra_files(pattern.to_s) }.filter_map do |path|
+        source = read_file(path, nil)
+        source if locales.include?(source[:locale])
+      end
+    end
+
+    # A glob may match nothing. A plain path is read as is, so a missing file raises.
+    def extra_files(pattern)
+      pattern.match?(GLOB_CHARS) ? Dir.glob(pattern).sort : [pattern]
+    end
+
+    def extra_word_sources(extra_words)
+      Array(extra_words).map do |hash|
+        raise InvalidWordListError, "#{EXTRA_SOURCE}: entry #{hash.inspect} is not a Hash" unless hash.is_a?(Hash)
+
+        attrs = hash.transform_keys(&:to_sym)
+        locale = attrs.delete(:locale)
+        unless LOCALES.include?(locale.respond_to?(:to_sym) ? locale.to_sym : nil)
+          raise InvalidWordListError,
+                "#{EXTRA_SOURCE}: entry #{hash[:stem].inspect} needs a locale (#{LOCALES.join(' or ')})"
+        end
+
+        check_variants(attrs, EXTRA_SOURCE)
+        locale = locale.to_sym
+        { locale: locale, path: EXTRA_SOURCE, prefixes: [], allow: [],
+          entries: [Entry.build(attrs, locale: locale, source: EXTRA_SOURCE)] }
+      end
+    end
+
+    # +locale+ is nil for extra files, which must declare it.
+    def read_file(path, locale)
+      data = YAML.safe_load(File.read(path)) # rubocop:disable Style/YAMLFileRead
+      fail_in(path, 'root must be a Hash') unless data.is_a?(Hash)
+      unknown = data.keys - FILE_KEYS
+      fail_in(path, "unknown top-level keys #{unknown.inspect}") unless unknown.empty?
+
+      locale ||= file_locale(data['locale'], path)
+      {
+        locale: locale,
+        path: path,
+        prefixes: string_list(data['prefixes'], 'prefixes', path),
+        allow: string_list(data['allow'], 'allow', path),
+        entries: build_entries(data['words'], locale, path)
+      }
+    rescue Psych::Exception, SystemCallError => e
+      raise InvalidWordListError, "#{path}: #{e.message}"
+    end
+
+    def file_locale(value, path)
+      locale = value.is_a?(String) ? value.to_sym : nil
+      return locale if LOCALES.include?(locale)
+
+      fail_in(path, "top-level locale must be one of #{LOCALES.inspect}, got #{value.inspect}")
+    end
+
+    def string_list(value, key, path)
+      return [] if value.nil?
+      return value.map { |w| w.dup.freeze }.freeze if value.is_a?(Array) && value.all?(String)
+
+      fail_in(path, "#{key} must be an Array of strings")
+    end
+
+    def build_entries(words, locale, path)
+      return [] if words.nil?
+      fail_in(path, 'words must be an Array') unless words.is_a?(Array)
+
+      words.map do |hash|
+        fail_in(path, "entry #{hash.inspect} must be a Hash") unless hash.is_a?(Hash)
+        check_variants(hash, path)
+        Entry.build(hash, locale: locale, source: path)
+      end
+    end
+
+    def check_variants(hash, path)
+      key = ['variants', :variants].find { |k| hash.key?(k) }
+      return unless key
+
+      variants = hash[key]
+      return if variants.is_a?(Array) && variants.all? { |v| v.is_a?(String) && !v.strip.empty? }
+
+      fail_in(path, "entry #{(hash['stem'] || hash[:stem]).inspect}: variants must be an Array of non-blank strings")
+    end
+
+    def fail_in(path, message)
+      raise InvalidWordListError, "#{path}: #{message}"
+    end
+  end
+end

data/lib/swear_jar.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'swear_jar/version'
+require_relative 'swear_jar/errors'
+require_relative 'swear_jar/match'
+require_relative 'swear_jar/entry'
+require_relative 'swear_jar/word_list'
+require_relative 'swear_jar/fold_table'
+require_relative 'swear_jar/normalizer'
+require_relative 'swear_jar/pattern_builder'
+require_relative 'swear_jar/skeleton'
+require_relative 'swear_jar/slicer'
+require_relative 'swear_jar/matcher'
+require_relative 'swear_jar/detector'
+
+module SwearJar
+  ROOT_PATH = File.expand_path('..', __dir__)
+
+  LOCALES = %i[pl en].freeze
+  SEVERITIES = %i[mild strong severe].freeze
+  CATEGORIES = %i[vulgar sexual insult slur religious].freeze
+  MODES = %i[words embedded].freeze
+end
+
+require_relative 'swear_jar/configuration'
+
+require_relative 'swear_jar/railtie' if defined?(Rails::Railtie)