knitsearch 0.1.0

data/lib/knitsearch/query.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Knitsearch
+  # FTS5 match-string builder. Escapes user input so it can't break out of FTS5
+  # syntax. Quotes each token, doubles internal quotes, strips control characters,
+  # and joins with the specified operator. Returns nil for empty input — the caller
+  # decides what to do (typically: return an empty relation).
+  module Query
+    extend self
+
+    CONTROL_CHARACTERS = /[\x00-\x1f\x7f]/
+
+    def escape(input, operator: :and, prefix: false, match: :word)
+      return nil if input.nil?
+
+      cleaned = input.to_s.gsub(CONTROL_CHARACTERS, " ").strip
+      return nil if cleaned.empty?
+
+      tokens = cleaned.split(/\s+/).reject(&:empty?)
+      return nil if tokens.empty?
+
+      case match
+      when :word
+        build_word_match(tokens, operator, prefix)
+      when :phrase
+        build_phrase_match(tokens, operator)
+      else
+        raise ArgumentError, "match must be :word or :phrase, got: #{match.inspect}"
+      end
+    end
+
+    private
+      def build_word_match(tokens, operator, prefix)
+        quoted = tokens.map { |t| %("#{t.gsub('"', '""')}") }
+        quoted = quoted.map { |t| "#{t}*" } if prefix
+
+        case operator
+        when :and
+          quoted.join(" ")
+        when :or
+          quoted.join(" OR ")
+        else
+          raise ArgumentError, "operator must be :and or :or, got: #{operator.inspect}"
+        end
+      end
+
+      def build_phrase_match(tokens, operator)
+        if operator == :or
+          raise ArgumentError,
+                "match: :phrase cannot be combined with operator: :or — a phrase is a single contiguous unit, not a set of terms to OR together"
+        end
+
+        escaped_tokens = tokens.map { |t| t.gsub('"', '""') }
+        %("#{escaped_tokens.join(' ')}")
+      end
+  end
+end

data/lib/knitsearch/version.rb

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

data/lib/knitsearch.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "active_support"
+
+require "knitsearch/version"
+require "knitsearch/engine"
+require "knitsearch/has_many_dependent"
+require "knitsearch/has_many_through_join_dependent"
+require "knitsearch/has_many_through_target_dependent"
+require "knitsearch/document"
+require "knitsearch/multisearchable"
+require "knitsearch/multisearchable_sync"
+
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/generators")
+loader.setup
+
+module Knitsearch
+  TOKENIZER_PRESETS = {
+    unicode: "unicode61 remove_diacritics 2",
+    ascii: "ascii",
+    porter: "porter",
+    trigram: "trigram"
+  }.freeze
+
+  WEIGHT_BUCKETS = {
+    "A" => 8,
+    "B" => 4,
+    "C" => 2,
+    "D" => 1
+  }.freeze
+
+  SUPPORTED_DICTIONARIES = %w[simple english trigram].freeze
+
+  class Error < StandardError; end
+  class SchemaMismatchError < Error; end
+  class ColumnError < Error; end
+  class UnknownDictionaryError < Error; end
+  class ConfigurationError < Error; end
+
+  class << self
+    attr_reader :belongs_to_dependents, :has_many_dependents, :has_many_through_dependents, :has_many_through_target_dependents
+
+    def belongs_to_dependents
+      @belongs_to_dependents ||= Hash.new { |h, k| h[k] = [] }
+    end
+
+    def has_many_dependents
+      @has_many_dependents ||= Hash.new { |h, k| h[k] = [] }
+    end
+
+    def has_many_through_dependents
+      @has_many_through_dependents ||= Hash.new { |h, k| h[k] = [] }
+    end
+
+    def has_many_through_target_dependents
+      @has_many_through_target_dependents ||= Hash.new { |h, k| h[k] = [] }
+    end
+
+    def multisearch(query, limit: nil)
+      return Document.none if query.blank?
+
+      escaped = Knitsearch::Query.escape(query, operator: :and, prefix: false, match: :word)
+      return Document.none if escaped.nil?
+
+      relation = Document
+        .joins("INNER JOIN knitsearches_fts ON knitsearches_fts.rowid = knitsearches.id")
+        .where("knitsearches_fts MATCH ?", escaped)
+        .order(Arel.sql("bm25(knitsearches_fts)"))
+
+      limit ? relation.limit(limit) : relation
+    end
+
+    def register_belongs_to_dependent(parent_class, child_class, foreign_key, shadow_map)
+      belongs_to_dependents[parent_class] << {
+        model: child_class,
+        foreign_key: foreign_key,
+        columns: shadow_map
+      }
+
+      # Install after_update_commit hook on parent class (idempotent)
+      unless parent_class.instance_variable_defined?(:@knitsearch_dependents_installed)
+        parent_class.instance_variable_set(:@knitsearch_dependents_installed, true)
+        parent_class.after_update_commit :knitsearch_cascade_to_children
+      end
+    end
+
+    def register_has_many_dependent(child_class, parent_class, inverse_fk, shadow_map, parent_assoc)
+      has_many_dependents[child_class] << {
+        parent: parent_class,
+        inverse_fk: inverse_fk,
+        columns: shadow_map,
+        parent_assoc: parent_assoc
+      }
+
+      child_class.include(HasManyDependent) unless child_class.include?(HasManyDependent)
+    end
+
+    def register_has_many_through_dependent(join_class:, target_class:, parent_class:, parent_fk:, target_fk:, parent_assoc:, shadow_map:)
+      # Store on join class side (for join create/destroy callbacks)
+      has_many_through_dependents[join_class] << {
+        parent_class: parent_class,
+        parent_fk: parent_fk,
+        target_class: target_class,
+        target_fk: target_fk,
+        parent_assoc: parent_assoc,
+        columns: shadow_map
+      }
+
+      # Store on target class side (for target update callbacks)
+      source_columns = shadow_map.values
+      has_many_through_target_dependents[target_class] << {
+        join_class: join_class,
+        parent_class: parent_class,
+        parent_fk: parent_fk,
+        target_fk: target_fk,
+        parent_assoc: parent_assoc,
+        columns: shadow_map,
+        source_columns: source_columns
+      }
+
+      # Install callbacks on both join and target classes
+      join_class.include(HasManyThroughJoinDependent) unless join_class.include?(HasManyThroughJoinDependent)
+      target_class.include(HasManyThroughTargetDependent) unless target_class.include?(HasManyThroughTargetDependent)
+    end
+  end
+end

data/lib/tasks/knitsearch.rake

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+namespace :knitsearch do
+  desc "Backfill the FTS index from existing records. Usage: bin/rails knitsearch:backfill[Article]"
+  task :backfill, [:model_name] => :environment do |_task, args|
+    model_name = args[:model_name]
+    raise "Model name required: bin/rails knitsearch:backfill[ModelName]" if model_name.blank?
+
+    model_class = model_name.classify.constantize
+    raise "#{model_name} does not include Knitsearch::Model" unless model_class.respond_to?(:knitsearch_backfill!)
+
+    puts "Backfilling search index for #{model_class.name}..."
+    model_class.knitsearch_backfill!
+    puts "Backfill complete. Source table has #{model_class.count} rows."
+  rescue NameError
+    raise "Could not find model #{model_name}"
+  end
+
+  desc "Rebuild the FTS5 index for a model. Usage: bin/rails knitsearch:reindex[Article]"
+  task :reindex, [:model_name] => :environment do |_task, args|
+    model_name = args[:model_name]
+    raise "Model name required: bin/rails knitsearch:reindex[ModelName]" if model_name.blank?
+
+    model_class = model_name.classify.constantize
+    raise "#{model_name} does not include Knitsearch::Model" unless model_class.respond_to?(:reindex!)
+
+    puts "Reindexing search for #{model_class.name}..."
+    model_class.reindex!
+    puts "Reindex complete for #{model_class.name}. Source table has #{model_class.count} rows."
+  rescue NameError
+    raise "Could not find model #{model_name}"
+  end
+end

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: knitsearch
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- knitsearch contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Knitsearch adds FTS5-backed full-text search to ActiveRecord models.
+  Search by rich text, associated records, or multiple models in one query. Index
+  updates synchronously via SQLite triggers, atomic with source writes. BM25-ranked
+  results returned as a chainable Relation. Supports typo tolerance, phrase matching,
+  prefix matching, highlighting, snippets, and more.
+email:
+- noreply@driveton.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/generators/knitsearch/install/install_generator.rb
+- lib/generators/knitsearch/install/templates/migration.rb.tt
+- lib/generators/knitsearch/multisearch_install/multisearch_install_generator.rb
+- lib/knitsearch.rb
+- lib/knitsearch/document.rb
+- lib/knitsearch/engine.rb
+- lib/knitsearch/fuzzy_corrector.rb
+- lib/knitsearch/has_many_dependent.rb
+- lib/knitsearch/has_many_through_join_dependent.rb
+- lib/knitsearch/has_many_through_target_dependent.rb
+- lib/knitsearch/highlighter.rb
+- lib/knitsearch/levenshtein.rb
+- lib/knitsearch/migration.rb
+- lib/knitsearch/model.rb
+- lib/knitsearch/multisearchable.rb
+- lib/knitsearch/multisearchable_sync.rb
+- lib/knitsearch/query.rb
+- lib/knitsearch/version.rb
+- lib/tasks/knitsearch.rake
+homepage: https://github.com/driveton/knitsearch
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/driveton/knitsearch
+  changelog_uri: https://github.com/driveton/knitsearch/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Full-text search for Rails 8 + SQLite with ActionText, associations, and
+  multi-model search.
+test_files: []