naughty_words 0.1.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d84f228f93cc6af5a7794aa4c42a56a45d1d8dd575982a687672cefa9991341
-  data.tar.gz: d2a64141e31b2a293fceef6fc5c58e8fe0a150db75c7d3be7227da5415948427
+  metadata.gz: 19600db4679a9894f5cebde198af0a4162aaa602b618189fcf26ef90f3b6cf28
+  data.tar.gz: 34828a7a2036b0f8a959e0ff41b7e6615c18c4d5cef49bb210cea3d6ed7ba7d2
 SHA512:
-  metadata.gz: eecf8555f6d2cfff3951c386caf6bdd428a0abaa9742ff552b773b33df938116553ffe859cbd2f365a332f428b6ce1be4743304512e948a668a474ce3d1ba1a1
-  data.tar.gz: 9817e7590058a2691b606acaecab6bff48a3a7abdd97ae3d914a96d53bf69c3fc4e2a2d943d7704902b6f7428ffb599c5fa771b732d3903413395628287c8cfe
+  metadata.gz: 97bc17c0ca656cbacf740519d3d9761342ae5fea4a4ac7858f2e018367f086db320a793d52c2fc59f3406190a7494ed33b9cfb3a9ea30114d98710824c255d18
+  data.tar.gz: fdb7d5fc29a1d10fb621d6efe6fc663e4a19b07ff5c5136d7b36a617af83254ace06d8740b3f689d9cf8ab3fcb24b3bd400cd71ed89ad5242458177e7705285f

data/README.md

@@ -1,6 +1,12 @@
 # NaughtyWords
 
-A super basic gem to check if a string has profanites. 
+A Ruby gem for filtering profanity from text. Features include:
+- Built-in deny and allow lists
+- Database integration for custom word lists
+- Runtime word overrides
+- Word boundary matching (for checks)
+- Case insensitive matching
+- Optional severity-based filtering for DB deny words
 
 ## Installation
 
@@ -11,75 +17,264 @@ gem 'naughty_words'
 ```
 
 And then execute:
-
-    $ bundle install
+```bash
+bundle install
+```
 
 Or install it yourself as:
+```bash
+gem install naughty_words
+```
+
+## Basic Usage
+
+```ruby
+# Check if a string contains profanity
+NaughtyWords.check(string: "hello world")  # => false
+NaughtyWords.check(string: "fuck this")    # => true
+
+# Filter profanity from a string
+NaughtyWords.filter(string: "hello world")  # => "hello world"
+NaughtyWords.filter(string: "fuck this")    # => "**** this"
+
+# Use custom replacement character
+NaughtyWords.filter(string: "fuck this", replacement: "@")  # => "@@@@ this"
+```
 
-    $ gem install naughty_words
+## Configuration
 
-## Usage
+Configure the gem's behavior:
 
-**Check if a string includes a profanity**
-The `check` method takes in a `string:` argument and will return a boolean.
 ```ruby
-    NaughtyWords.check(string: "ass")
-    => true
+NaughtyWords.configure do |config|
+  # Match whole words only (default: true)
+  # When true: "fuck" matches "fuck" but not "fuckthis"
+  # When false: "fuck" matches both "fuck" and "fuckthis"
+  config.word_boundaries = true
 
-    NaughtyWords.check(string: "hello world")
-    => false
+  # Use built-in word lists (default: true)
+  # Set to false to use only database or runtime overrides
+  config.use_built_in_lists = true
 
-    NaughtyWords.check(string: "hello asshole")
-    => true
+  # Only consider DB deny words at or above this severity (optional)
+  # One of: "high", "medium", "low". nil means all severities.
+  config.minimum_severity = nil
+end
+
+# For tests or to return to defaults
+NaughtyWords::Config.reset!
 ```
 
-**Filter out words**
-The `filter` method takes a `string:` argument and an optional `replacement:` argument.
+## Database Integration
+
+The gem can use a database (ActiveRecord) to store custom word lists.
 
-``` ruby
-    # passing a string with no profanity will return the string
-    NaughtyWords.filter(string: "hello world")
-    => "hello world"
-    
-    # passing a string with profanities will return the string with the profanity filtered out
-    NaughtyWords.filter(string: "hello asshole")
-    => "hello *******"
-    
-    # you can use in your own filter character by passing it in as an argument  ("*" is by default)
-    NaughtyWords.filter(string: "hello asshole", replacement: "!")
-    => "hello !!!!!!!"
+1) Install migration, model, and initializer (recommended):
+```bash
+rails generate naughty_words:install
 ```
 
-Note: Current, this is comically easy to circumvent. String like "shitshitshit" will only filter out the first match, returning "*****shitshit". A fix is enroute.
+This adds:
+- db/migrate/create_naughty_words_lists.rb
+- app/models/naughty_words/word_list.rb
+- config/initializers/naughty_words.rb
 
-### Validating in Rails example
-We can use a custom validator in our User model to make sure a user cannot sign up with a username containing profanities in tandem with our normal `validates` methods.
+2) Add optional columns if you need them
+
+If you plan to use `category`, `severity` ("high" | "medium" | "low"), or `metadata` (JSON), add these columns to your migration before running it. Example:
 
 ```ruby
-# app/models/user.rb
+change_table :naughty_words_lists do |t|
+  t.string :category        # optional
+  t.string :severity        # optional, one of "high", "medium", "low"
+  t.json   :metadata, default: {}  # optional
+end
+```
 
-validates :username, uniqueness: true, presence: true # basic username validation 
-validate :username_profanity_check # our custom validator
+Then run:
+```bash
+rails db:migrate
+```
 
-...
+3) Add words to your lists:
+```ruby
+# Basic usage
+NaughtyWords::WordList.create!(word: "badword", list_type: "deny")
+NaughtyWords::WordList.create!(word: "scunthorpe", list_type: "allow")
 
-def username_profanity_check
-    errors.add(:username, "contains profanity") if NaughtyWords.check(string: username)
-end
+# With optional metadata (requires columns above)
+NaughtyWords::WordList.create!(
+  word: "badword",
+  list_type: "deny",
+  context: "Added due to user complaints",
+  added_by: "john@example.com",
+  severity: "high",
+  category: "insults",
+  metadata: { reported_by: "forum_moderator" }
+)
+```
+
+4) View your lists:
+```ruby
+# Get just the words
+NaughtyWords.show_list(list: "deny")
+# => ["badword", "otherbadword", ...]
+
+# Get full records with metadata
+records = NaughtyWords.show_list(list: "deny", include_metadata: true)
+records.first
+# => #<NaughtyWords::WordList ... word: "badword", list_type: "deny", ...>
+
+# Query with metadata (if you use it)
+words = NaughtyWords::WordList.where(list_type: "deny")
+                             .where(added_by: "john@example.com")
+                             .where("metadata->>'category' = ?", "insults")
+```
+
+### View only the built-in default lists
+
+If you want to see the gem's built-in lists (ignoring anything in your database):
+
+```ruby
+# Ensure built-ins are enabled (default: true)
+NaughtyWords::Config.use_built_in_lists = true
+
+# If you have no DB entries, this already shows the built-ins
+NaughtyWords.show_list(list: "deny")   # => built-in deny words
+NaughtyWords.show_list(list: "allow")  # => built-in allow words
+
+# If you DO have DB entries and want to isolate the built-ins only:
+built_in_deny  = NaughtyWords.show_list(list: "deny")  - NaughtyWords::WordList.deny_list.pluck(:word)
+built_in_allow = NaughtyWords.show_list(list: "allow") - NaughtyWords::WordList.allow_list.pluck(:word)
+
+built_in_deny.first(10)
+```
+
+5) Severity-based checks from DB (optional)
+```ruby
+# Only consider DB deny words at or above "medium"
+NaughtyWords.configure { |c| c.minimum_severity = "medium" }
+
+# Or query explicitly via scopes
+NaughtyWords::WordList.by_severity("high").pluck(:word)
+NaughtyWords::WordList.by_severity("high").by_category("insults").pluck(:word)
+```
+
+If you don't install the DB table, the gem will work using only the built-in lists.
+
+## Runtime Overrides
+
+Override word lists temporarily during runtime:
+
+```ruby
+# Allow a word that's normally blocked
+NaughtyWords::Config.allow_word("someword")
+
+# Block a word that's normally allowed
+NaughtyWords::Config.deny_word("otherword")
+
+# Remove an override
+NaughtyWords::Config.remove_override("someword")
+```
+
+Overrides:
+- Take precedence over both built-in lists and database lists
+- Are case insensitive
+- Reset when your application restarts
+- Perfect for testing or temporary customizations
+
+## How It Works
+
+1) When checking/filtering text:
+   - First checks runtime overrides
+   - Then checks built-in lists (if enabled)
+   - Then checks database lists (if present)
+
+2) Word matching is:
+   - Always case insensitive
+   - Configurable for word boundaries (affects checks)
+   - Handles special characters and spaces
+
+3) Priority order:
+   1. Runtime overrides (highest)
+   2. Built-in lists
+   3. Database lists (lowest)
+
+4) Filtering details:
+   - Replacement proceeds longest-to-shortest denied words.
+   - Filtering masks any occurrence of denied words (case-insensitive), regardless of `word_boundaries`.
+   - Example: with boundaries on, `check` may pass for “scunthorpe”, but if “cunt” is denied, `filter` will still mask “cunt” inside “scunthorpe”.
+
+## Default list philosophy
+
+The built-in deny list is intentionally minimal and neutral by default.
+
+- Focuses on single-word profanities and slurs only
+- Avoids medical/sexual terms and general sexual content
+- Avoids multi-word phrases and “moral policing”
+
+Customize to your community via the database layer:
+- Add phrases (e.g., “eat my ass”) to `naughty_words_lists` with `category`/`severity`
+- Use `minimum_severity` to tune strictness globally
+- Use runtime overrides for temporary exceptions
+
+## Examples
+
+### Basic Filtering
+```ruby
+# Simple profanity check
+NaughtyWords.check(string: "hello world")  # => false
+NaughtyWords.check(string: "fuck this")    # => true
+
+# Filter with default replacement (*)
+NaughtyWords.filter(string: "fuck this")  # => "**** this"
+
+# Custom replacement character
+NaughtyWords.filter(string: "fuck this", replacement: "@")  # => "@@@@ this"
+```
+
+### Word Boundaries
+```ruby
+# With word_boundaries = true (default)
+NaughtyWords.check(string: "fuck")      # => true
+NaughtyWords.check(string: "fuckthis")  # => false
+
+# With word_boundaries = false
+NaughtyWords.configure { |c| c.word_boundaries = false }
+NaughtyWords.check(string: "fuckthis")  # => true
 ```
 
-## Development
+### Database Integration
+```ruby
+# Add custom words
+NaughtyWords::WordList.create!(word: "badword", list_type: "deny")
+NaughtyWords::WordList.create!(word: "goodword", list_type: "allow")
+
+# View lists with metadata
+NaughtyWords.show_list(list: "deny", include_metadata: true)
+# => [#<NaughtyWords::WordList id: 1, word: "badword", list_type: "deny", created_at: ...>]
+```
+
+### Runtime Overrides
+```ruby
+# Override the built-in lists
+NaughtyWords::Config.allow_word("fuck")  # Allow this word
+NaughtyWords.check(string: "fuck")       # => false
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+# Multiple overrides
+NaughtyWords::Config.allow_word("fuck")
+NaughtyWords::Config.allow_word("shit")
+NaughtyWords.filter(string: "fuck this shit")  # => "fuck this shit"
+
+# Remove overrides
+NaughtyWords::Config.remove_override("fuck")
+NaughtyWords.check(string: "fuck")  # => true (back to default)
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/jaarnie/naughty_words. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/jaarnie/naughty_words/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at `https://github.com/jaarnie/naughty_words`.
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the NaughtyWords project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/naughty_words/blob/master/CODE_OF_CONDUCT.md).

data/lib/generators/naughty_words/install/install_generator.rb

@@ -0,0 +1,32 @@
+
+# frozen_string_literal: true
+
+module NaughtyWords
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(path)
+        next_migration_number = current_migration_number(path) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def copy_migrations
+        migration_template(
+          "create_naughty_words_lists.rb",
+          "db/migrate/create_naughty_words_lists.rb"
+        )
+      end
+
+      def copy_models
+        template "word_list.rb", "app/models/naughty_words/word_list.rb"
+      end
+
+      def copy_initializer
+        template "initializer.rb", "config/initializers/naughty_words.rb"
+      end
+    end
+  end
+end

data/lib/generators/naughty_words/install/templates/create_naughty_words_lists.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreateNaughtyWordsLists < ActiveRecord::Migration[7.0]
+  def change
+    create_table :naughty_words_lists do |t|
+      t.string :word, null: false
+      t.string :list_type, null: false # 'deny' or 'allow'
+      t.string :category
+      t.string :severity               # "high" | "medium" | "low"
+      t.text   :context
+      t.string :added_by
+      t.json   :metadata, default: {}
+      t.timestamps
+
+      t.index [:word, :list_type], unique: true
+      t.index :category
+      t.index :severity
+    end
+  end
+end 

data/lib/generators/naughty_words/install/templates/initializer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+NaughtyWords.configure do |config|
+  # Match whole words only (default: true). Set false to allow substrings.
+  config.word_boundaries = true
+
+  # Include built-in allow/deny lists (default: true).
+  config.use_built_in_lists = true
+
+  # Optional: only consider DB deny words at or above this severity.
+  # One of: "high", "medium", "low"; nil means all severities.
+  config.minimum_severity = nil
+end

data/lib/generators/naughty_words/install/templates/word_list.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module NaughtyWords
+  class WordList < ActiveRecord::Base
+    self.table_name = "naughty_words_lists"
+
+    validates :word, presence: true
+    validates :list_type, presence: true, inclusion: { in: %w[deny allow] }
+    validates :word, uniqueness: { scope: :list_type }
+    validates :severity, inclusion: { in: %w[high medium low], allow_nil: true }
+
+    scope :deny_list,   -> { where(list_type: "deny") }
+    scope :allow_list,  -> { where(list_type: "allow") }
+    scope :by_category, ->(category) { where(category: category) }
+    scope :by_severity, ->(severity) { where(severity: severity) }
+    scope :added_by,    ->(user)     { where(added_by: user) }
+
+    before_save :normalize_word
+
+    private
+
+    def normalize_word
+      self.word = word.strip.downcase if word.present?
+    end
+  end
+end

data/lib/naughty_words/base.rb

@@ -1,56 +1,160 @@
 # frozen_string_literal: true
 
+require_relative "config"
+
 module NaughtyWords
   class Base
     class << self
       def profanity?(string:)
-        allow_list_array.each do |line|
-          return false if string.include?(line)
+        validate_input!(string)
+        normalized_string = normalize_string(string)
+
+        return false if word_in_list?(normalized_string, Config.allow_overrides)
+        return true if word_in_list?(normalized_string, Config.deny_overrides)
+
+        return false if Config.use_built_in_lists && word_in_list?(normalized_string, allow_list_from_files)
+        return false if word_in_list?(normalized_string, allow_list_from_db)
+
+        return true if Config.use_built_in_lists && word_in_list?(normalized_string, deny_list_from_files)
+        return true if word_in_list?(normalized_string, deny_list_from_db)
+
+        false
+      end
+
+      def filter(string:, replacement: "*")
+        validate_input!(string)
+        validate_replacement!(replacement)
+        result = string.dup
+
+        denied_words = Config.deny_overrides.dup
+        denied_words += deny_list_from_files if Config.use_built_in_lists
+        denied_words += deny_list_from_db
+        denied_words -= Config.allow_overrides # Remove any allowed overrides
+        denied_words = denied_words.sort_by(&:length).reverse
+
+        denied_words.each do |word|
+          next if word.empty?
+          result.gsub!(/#{Regexp.escape(word)}/i, replacement * word.length)
         end
 
-        deny_list_array.each do |line|
-          return true if string.include?(line)
+        result
+      end
+
+      def show_list(list:, include_metadata: false)
+        validate_list!(list)
+        
+        if include_metadata && defined?(WordList)
+          WordList.where(list_type: list)
+        else
+          words = []
+          words += (list == "deny" ? deny_list_from_files : allow_list_from_files) if Config.use_built_in_lists
+          words += (list == "deny" ? deny_list_from_db : allow_list_from_db)
+          words
         end
+      end
 
-        false
+      private
+
+      def deny_list_from_files
+        @deny_list_from_files ||= load_list(deny_list_path)
+      end
+
+      def allow_list_from_files
+        @allow_list_from_files ||= load_list(allow_list_path)
       end
 
-      def filter(string:, replacement:)
-        # TODO: Fix filtering full words ending with 'ing' and repeated words such as 'fuckfuckfuck'
-        deny_list_array.each do |line|
-          word = line
-          string.gsub!(word, replacement * word.length)
+      def deny_list_from_db
+        return [] unless db_table_available?
+        query = WordList.deny_list
+
+        if Config.minimum_severity
+          severities = %w[high medium low]
+          min_index = severities.index(Config.minimum_severity)
+          return [] unless min_index
+          allowed_severities = severities[0..min_index]
+          query = query.where(severity: allowed_severities)
         end
 
-        string
+        query.pluck(:word)
+      rescue StandardError
+        []
+      end
+
+      def allow_list_from_db
+        return [] unless db_table_available?
+        WordList.allow_list.pluck(:word)
+      rescue StandardError
+        []
+      end
+
+      def deny_list_path
+        File.join(File.dirname(File.expand_path(__FILE__)), "config/deny_list.txt")
+      end
+
+      def allow_list_path
+        File.join(File.dirname(File.expand_path(__FILE__)), "config/allow_list.txt")
+      end
+
+      def load_list(path)
+        return [] unless Config.use_built_in_lists
+        File.readlines(path, chomp: true).reject(&:empty?)
+      rescue Errno::ENOENT
+        raise Error, "List file not found: #{path}"
+      rescue IOError => e
+        raise Error, "Failed to read list: #{e.message}"
       end
 
-      def add_to_list(list:, string:)
-        File.open(send(list), "a+") do |file|
-          file.puts(string)
+      def word_in_list?(string, list)
+        list.any? do |word|
+          normalized_word = normalize_string(word)
+          word_match?(string, normalized_word)
         end
       end
 
-      def show_list(list:)
-        if list == "deny"
-          deny_list_array
+      def normalize_string(str)
+        str.downcase
+      end
+
+      def word_pattern(word)
+        escaped = Regexp.escape(word)
+        if Config.word_boundaries
+          /(?:^|[^a-zA-Z0-9])#{escaped}(?:$|[^a-zA-Z0-9])/i
         else
-          allow_list_array
+          /#{escaped}/i
         end
       end
 
-      private
+      def word_match?(string, word)
+        pattern = Config.word_boundaries ? 
+          /(?:^|[^a-zA-Z0-9])#{Regexp.escape(word)}(?:$|[^a-zA-Z0-9])/i : 
+          /#{Regexp.escape(word)}/i
+        string.match?(pattern)
+      end
 
-      def deny_list_array
-        file = File.open(File.join(File.dirname(File.expand_path(__FILE__)), "config/deny_list.txt"))
+      def validate_input!(string)
+        raise ArgumentError, "Input string cannot be nil" if string.nil?
+        raise ArgumentError, "Input string must be a String" unless string.is_a?(String)
+      end
 
-        @deny_list_array ||= File.readlines(file, chomp: true)
+      def validate_replacement!(replacement)
+        raise ArgumentError, "Replacement cannot be nil" if replacement.nil?
+        raise ArgumentError, "Replacement must be a String" unless replacement.is_a?(String)
+        raise ArgumentError, "Replacement cannot be empty" if replacement.empty?
       end
 
-      def allow_list_array
-        file = File.open(File.join(File.dirname(File.expand_path(__FILE__)), "config/allow_list.txt"))
+      def validate_list!(list)
+        valid_lists = ["deny", "allow"]
+        unless valid_lists.include?(list)
+          raise ArgumentError, "Invalid list type. Must be one of: #{valid_lists.join(', ')}"
+        end
+      end
 
-        @allow_list_array ||= File.readlines(file, chomp: true)
+      def db_table_available?
+        return false unless defined?(WordList) && defined?(ActiveRecord::Base)
+        conn = ActiveRecord::Base.connection
+        conn.data_source_exists?(WordList.table_name)
+      rescue StandardError
+        false
       end
     end
   end