column_sifter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2ad6e4ce81ed31d83084bdacbb06b7583d8fb148a894e331d7a3384e136e781b
+  data.tar.gz: 62b2bcc42128031d411aa7038e0e90feab92fa8f89e83cddc679f06239e43e34
+SHA512:
+  metadata.gz: 5a19e774198b0c5a6f1fad47acac3abbb00f3629ba81c36438f719f2664dd71cd66db0e6088f8b8c17d6bdbf9fc7d523f2cbbf0e13bb7e2eb79944d800df5575
+  data.tar.gz: 46e2ecd71a3f21ee6b09163a53678526e5b511fd9c3adbf6c6f3f5609e7e503a79bd9d7f89e75b2d76efa4d8f5ace489e6d722a35400de2058d1aad380fe2f0a

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 kyuuri1791
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,91 @@
+# ColumnSifter
+
+ColumnSifter provides SQL-like column filtering for admin screens: it turns a `WHERE`-like expression string into a SQL-injection-safe ActiveRecord `where` condition.
+
+![Admin screen filtering articles with a SQL-like query](demo.png)
+
+User input is run through a custom lexer → parser → compiler, and the condition is assembled so that:
+
+- values → passed via bind placeholders (`?`)
+- column names → only canonical names matched against a whitelist (`searchable_columns`) are emitted
+- operators → fixed tokens only
+
+so no raw input string leaks into the SQL.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'column_sifter'
+```
+
+## Usage
+
+Subclass `ColumnSifter::Base` and declare the columns you allow filtering on with `searchable_columns`.
+The target model is resolved from the class name with the `Sifter` suffix stripped (e.g. `ArticleSifter` → `Article`).
+
+```ruby
+# app/column_sifters/article_sifter.rb
+class ArticleSifter < ColumnSifter::Base
+  searchable_columns(:id, :author_id, :status, :published_at)
+end
+```
+
+If the model can't be resolved from the class name (different name, namespaced, etc.), declare it explicitly with `model`:
+
+```ruby
+class ArticleSifter < ColumnSifter::Base
+  model BlogPost
+  searchable_columns(:id, :author_id, :status, :published_at)
+end
+```
+
+Instantiate the sifter, pass the expression to `sift!`, and use the result to build the query:
+
+```ruby
+class ArticlesController < ApplicationController
+  def index
+    @sifter = ArticleSifter.new
+    @sifter.sift!(params[:sift_query])
+
+    @articles =
+      if @sifter.error.blank?
+        Article.where(@sifter.sql_template, *@sifter.binds)
+      else
+        Article.none
+      end
+  end
+end
+```
+
+`sift!` is a bang method that mutates the instance, storing the result internally. You can then read:
+
+- `sql_template` … the SQL fragment with placeholders
+- `binds` … the array of values for the placeholders
+- `input` … the given input string
+- `error` … the parse error message (`nil` on success)
+
+A search form for the expression:
+
+```erb
+<%= form_with url: articles_path, method: :get do %>
+  <%= text_field_tag :sift_query, @sifter&.input,
+                     placeholder: "status = 1 AND author_id IN (1, 2, 3)" %>
+  <% if @sifter&.error %>
+    <div><%= @sifter.error %></div>
+  <% end %>
+  <small>searchable columns: <%= ArticleSifter.searchable_columns.join(', ') %></small>
+  <%= submit_tag 'Search' %>
+<% end %>
+```
+
+## Supported syntax
+
+- comparison operators: `=` `!=` `<>` `>` `>=` `<` `<=`
+- `IN (...)`
+- `IS NULL` / `IS NOT NULL`
+- combinators: `AND` `OR` `NOT` and parentheses `()`
+
+## License
+
+MIT

data/lib/column_sifter/base/compiler.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module ColumnSifter
+  class Base
+    class Compiler
+      TEMPORAL_TYPES = %i[datetime date time].freeze
+
+      def initialize(allowed_columns, model)
+        @allowed_columns = allowed_columns
+        @model = model
+      end
+
+      def compile(node)
+        case node[:type]
+        when :and    then combine('AND', node[:children])
+        when :or     then combine('OR', node[:children])
+        when :not    then compile_not(node)
+        when :cmp    then compile_cmp(node)
+        when :in     then compile_in(node)
+        when :is_null then compile_is_null(node)
+        else
+          raise ParseError, "unknown node: #{node[:type]}"
+        end
+      end
+
+      private
+
+      def combine(keyword, children)
+        sqls = []
+        binds = []
+        children.each do |child|
+          sql, *child_binds = compile(child)
+          sqls << "(#{sql})"
+          binds.concat(child_binds)
+        end
+        [sqls.join(" #{keyword} ").to_s, *binds]
+      end
+
+      def compile_not(node)
+        sql, *binds = compile(node[:child])
+        ["NOT (#{sql})", *binds]
+      end
+
+      def compile_cmp(node)
+        column = column!(node[:column])
+        validate_value!(column, node[:value])
+        ["#{qualify(column)} #{node[:op]} ?", node[:value]]
+      end
+
+      def compile_in(node)
+        column = column!(node[:column])
+        node[:values].each { |value| validate_value!(column, value) }
+        placeholders = Array.new(node[:values].size, '?').join(', ')
+        ["#{qualify(column)} IN (#{placeholders})", *node[:values]]
+      end
+
+      def compile_is_null(node)
+        ["#{qualify(column!(node[:column]))} IS #{node[:negated] ? 'NOT ' : ''}NULL"]
+      end
+
+      def column!(name)
+        column = @allowed_columns.find { |allowed| allowed.casecmp?(name) }
+        raise ParseError, "column not searchable: #{name} (searchable: #{@allowed_columns.join(', ')})" unless column
+
+        column
+      end
+
+      def qualify(column)
+        "#{@model.table_name}.#{column}"
+      end
+
+      def validate_value!(column, value)
+        type = @model.type_for_attribute(column)
+        return unless TEMPORAL_TYPES.include?(type.type)
+        return if type.cast(value)
+
+        raise ParseError, "invalid date/time value for #{column}: #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/column_sifter/base/lexer.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module ColumnSifter
+  class Base
+    class Lexer
+      Token = Struct.new(:type, :value)
+      KEYWORDS = %w[AND OR NOT IS NULL IN].freeze
+      PATTERNS = [
+        [:ws,     /\A\s+/],
+        [:lparen, /\A\(/],
+        [:rparen, /\A\)/],
+        [:comma,  /\A,/],
+        [:op,     /\A(?:<=|>=|<>|!=|=|<|>)/],
+        [:number, /\A-?\d+(?:\.\d+)?/],
+        [:string, /\A'(?:[^']|'')*'/],
+        [:string, /\A"(?:[^"]|"")*"/],
+        [:ident,  /\A[A-Za-z_][A-Za-z0-9_]*/]
+      ].freeze
+
+      def initialize(input)
+        @input = input.to_s
+      end
+
+      def tokenize
+        rest = @input
+        tokens = []
+
+        until rest.empty?
+          type, matched = match_token(rest)
+          raise ParseError, "unable to parse near: #{rest[0..10].inspect}" if matched.nil?
+
+          rest = rest[matched.length..]
+          next if type == :ws
+
+          tokens << build_token(type, matched)
+        end
+
+        tokens
+      end
+
+      private
+
+      def match_token(rest)
+        PATTERNS.each do |type, pattern|
+          m = rest.match(pattern)
+          return [type, m[0]] if m
+        end
+        [nil, nil]
+      end
+
+      def build_token(type, matched)
+        case type
+        when :number
+          Token.new(:number, matched.include?('.') ? matched.to_f : matched.to_i)
+        when :string
+          Token.new(:string, unquote(matched))
+        when :ident
+          keyword?(matched) ? Token.new(:keyword, matched.upcase) : Token.new(:ident, matched)
+        else
+          Token.new(type, matched)
+        end
+      end
+
+      def keyword?(ident)
+        KEYWORDS.include?(ident.upcase)
+      end
+
+      def unquote(literal)
+        quote = literal[0]
+        literal[1..-2].gsub(quote * 2, quote)
+      end
+    end
+  end
+end

data/lib/column_sifter/base/parser.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module ColumnSifter
+  class Base
+    class Parser
+      MAX_DEPTH = 100
+
+      def initialize(tokens)
+        @tokens = tokens
+        @pos = 0
+        @depth = 0
+      end
+
+      def parse
+        raise ParseError, 'query is empty' if @tokens.empty?
+
+        node = parse_or
+        raise ParseError, "unexpected token: #{peek.value.inspect}" unless at_end?
+
+        node
+      end
+
+      private
+
+      def parse_or
+        nodes = [parse_and]
+        nodes << parse_and while accept_keyword('OR')
+        nodes.size == 1 ? nodes.first : { type: :or, children: nodes }
+      end
+
+      def parse_and
+        nodes = [parse_not]
+        nodes << parse_not while accept_keyword('AND')
+        nodes.size == 1 ? nodes.first : { type: :and, children: nodes }
+      end
+
+      def parse_not
+        return descend { { type: :not, child: parse_not } } if accept_keyword('NOT')
+
+        parse_primary
+      end
+
+      def parse_primary
+        if accept(:lparen)
+          node = descend { parse_or }
+          expect(:rparen)
+          return node
+        end
+
+        parse_condition
+      end
+
+      def descend
+        @depth += 1
+        raise ParseError, 'expression is too deeply nested' if @depth > MAX_DEPTH
+
+        result = yield
+        @depth -= 1
+        result
+      end
+
+      def parse_condition
+        column = expect(:ident).value
+
+        if accept_keyword('IS')
+          negated = accept_keyword('NOT') ? true : false
+          expect_keyword('NULL')
+          return { type: :is_null, column: column, negated: negated }
+        end
+
+        if accept_keyword('IN')
+          expect(:lparen)
+          values = [expect_value]
+          values << expect_value while accept(:comma)
+          expect(:rparen)
+          return { type: :in, column: column, values: values }
+        end
+
+        op = expect(:op).value
+        { type: :cmp, column: column, op: op, value: expect_value }
+      end
+
+      def expect_value
+        token = peek
+        unless token && %i[number string].include?(token.type)
+          raise ParseError, "a value (number or 'string') is required; use IS NULL to compare with NULL"
+        end
+
+        advance.value
+      end
+
+      def peek
+        @tokens[@pos]
+      end
+
+      def at_end?
+        @pos >= @tokens.length
+      end
+
+      def advance
+        token = @tokens[@pos]
+        @pos += 1
+        token
+      end
+
+      def accept(type)
+        return nil unless peek&.type == type
+
+        advance
+      end
+
+      def accept_keyword(keyword)
+        return nil unless peek&.type == :keyword && peek.value == keyword
+
+        advance
+      end
+
+      def expect(type)
+        token = accept(type)
+        raise ParseError, "expected #{type} but got #{describe(peek)}" unless token
+
+        token
+      end
+
+      def expect_keyword(keyword)
+        token = accept_keyword(keyword)
+        raise ParseError, "expected #{keyword} but got #{describe(peek)}" unless token
+
+        token
+      end
+
+      def describe(token)
+        token ? token.value.inspect : 'end of input'
+      end
+    end
+  end
+end

data/lib/column_sifter/base/result.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ColumnSifter
+  class Base
+    class Result
+      attr_accessor :input, :error, :sql_template, :binds
+    end
+  end
+end

data/lib/column_sifter/base.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module ColumnSifter
+  class Base
+    extend Forwardable
+
+    class ParseError < StandardError; end
+
+    def_delegators :@result, :input, :error, :sql_template, :binds
+
+    def initialize
+      @result = Result.new
+    end
+
+    def sift!(input)
+      tokens = Lexer.new(input).tokenize
+      ast = Parser.new(tokens).parse
+      sql_template, *binds = Compiler.new(self.class.searchable_columns, self.class.model).compile(ast)
+      @result.input = input
+      @result.sql_template = sql_template
+      @result.binds = binds
+    rescue ParseError => e
+      @result.input = input
+      @result.error = e.message
+    end
+
+    class << self
+      def model(model = nil)
+        @model = model if model
+        @model ||= Object.const_get(name.split('::').last.delete_suffix('Sifter'))
+      end
+
+      def searchable_columns(*columns)
+        @searchable_columns = columns.map(&:to_s).freeze if columns.any?
+        @searchable_columns || raise(NotImplementedError, "#{self}.searchable_columns must be declared")
+      end
+    end
+  end
+end

data/lib/column_sifter/version.rb

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

data/lib/column_sifter.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'column_sifter/version'
+require_relative 'column_sifter/base'
+require_relative 'column_sifter/base/result'
+require_relative 'column_sifter/base/lexer'
+require_relative 'column_sifter/base/parser'
+require_relative 'column_sifter/base/compiler'

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: column_sifter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- kyuuri1791
+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: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Turns a SQL WHERE-like expression string into a SQL-injection-safe ActiveRecord
+  where condition. Intended for admin screens that need flexible filtering over a
+  whitelisted set of columns.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/column_sifter.rb
+- lib/column_sifter/base.rb
+- lib/column_sifter/base/compiler.rb
+- lib/column_sifter/base/lexer.rb
+- lib/column_sifter/base/parser.rb
+- lib/column_sifter/base/result.rb
+- lib/column_sifter/version.rb
+homepage: https://github.com/kyuuri1791/column_sifter
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kyuuri1791/column_sifter
+  source_code_uri: https://github.com/kyuuri1791/column_sifter
+  bug_tracker_uri: https://github.com/kyuuri1791/column_sifter/issues
+  changelog_uri: https://github.com/kyuuri1791/column_sifter/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.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: SQL-like, injection-safe column filtering for ActiveRecord.
+test_files: []