jql_ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5a08c2507174f677a6b35095285197a2a58f1114946e86b68a7a440a95bbc1bc
+  data.tar.gz: cf908b48b100e8336c598fa5b8dd42ba4c506395dd6b45cbe3b46af07f61953c
+SHA512:
+  metadata.gz: 53de7669ff8f13e8191341a2754da46d31af20510a81158e68840b5162a71c25e0c3ae1ef2cb112fbf98532fc3f3be7f21780f2a7ee82574ba15839cc120ab12
+  data.tar.gz: 50f81f5ef39112880e2e269930bee53f911e0149b68624c6ea319cf794a44a857b118a741fc47d6a12d4f8a9a68f555350114ca5be332304eebb82fa7c791d4d

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-04-05
+
+### Added
+
+- Recursive descent parser for the full JQL grammar (AND, OR, NOT, parentheses, ORDER BY)
+- Terminal clause operators: `=`, `!=`, `<`, `>`, `<=`, `>=`, `~`, `!~`, `IN`, `NOT IN`, `IS`, `IS NOT`, `WAS`, `WAS NOT`, `WAS IN`, `WAS NOT IN`, `CHANGED`
+- WAS/CHANGED predicate support: `AFTER`, `BEFORE`, `DURING`, `ON`, `BY`, `FROM`, `TO`
+- Function operands (e.g. `currentUser()`, `startOfMonth("-1")`)
+- Custom field syntax (`cf[10001]`)
+- Quoted and unquoted string values, numbers
+- AST node classes with visitor-pattern `accept` methods
+- Adapter pattern for ORM integration (`Adapters::Base`)
+- ActiveRecord adapter with Arel-based query building
+- Configurable field mapping (simple column, or custom resolver block)
+- Configurable function resolvers with runtime context

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ignition App Pty Ltd
+
+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,231 @@
+# JqlRuby
+
+A pure-Ruby parser for [Jira Query Language (JQL)](https://support.atlassian.com/jira-software-cloud/docs/use-advanced-search-with-jira-query-language-jql/). Parses JQL strings into an abstract syntax tree and optionally converts them into ORM queries via an adapter pattern.
+
+The grammar is modeled after Atlassian's [@atlaskit/jql-parser](https://www.npmjs.com/package/@atlaskit/jql-parser).
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "jql_ruby"
+```
+
+Or install directly:
+
+```
+gem install jql_ruby
+```
+
+## Quick Start
+
+```ruby
+result = JqlRuby.parse('project = MYPROJ AND status = Open ORDER BY created DESC')
+
+result.success? # => true
+result.query    # => JqlRuby::Ast::Query
+
+result.query.where_clause # => JqlRuby::Ast::AndClause
+result.query.order_by     # => JqlRuby::Ast::OrderBy
+```
+
+## Supported Grammar
+
+JqlRuby supports the full JQL specification:
+
+| Category | Syntax |
+|---|---|
+| **Equality** | `=`, `!=` |
+| **Comparison** | `<`, `>`, `<=`, `>=` |
+| **Contains** | `~` (LIKE), `!~` (NOT LIKE) |
+| **Set** | `IN (...)`, `NOT IN (...)` |
+| **Null checks** | `IS EMPTY`, `IS NOT EMPTY`, `IS NULL`, `IS NOT NULL` |
+| **History** | `WAS`, `WAS NOT`, `WAS IN`, `WAS NOT IN` |
+| **Change** | `CHANGED` |
+| **Predicates** | `AFTER`, `BEFORE`, `DURING`, `ON`, `BY`, `FROM`, `TO` |
+| **Logical** | `AND`, `OR`, `NOT`, `!`, parentheses |
+| **Ordering** | `ORDER BY field ASC/DESC` |
+| **Functions** | `currentUser()`, `now()`, any `name(args...)` |
+| **Custom fields** | `cf[10001]` |
+
+## AST Nodes
+
+Parsing produces a tree of AST nodes:
+
+```
+Query
+├── where_clause (one of:)
+│   ├── TerminalClause  — field, operator, operand, predicates
+│   ├── AndClause       — clauses[]
+│   ├── OrClause        — clauses[]
+│   └── NotClause       — clause, operator (:not or :bang)
+└── order_by
+    └── OrderBy         — fields[] of SearchSort (field, direction)
+```
+
+### Operand types
+
+- `ValueOperand` — string or number literal
+- `FunctionOperand` — function name + arguments
+- `ListOperand` — parenthesized list of operands
+- `KeywordOperand` — `EMPTY` or `NULL`
+
+### Working with the AST
+
+```ruby
+result = JqlRuby.parse('priority = High AND duedate < now()')
+clause = result.query.where_clause # => AndClause
+
+clause.clauses[0].field.name       # => "priority"
+clause.clauses[0].operator.value   # => :eq
+clause.clauses[0].operand.value    # => "High"
+
+clause.clauses[1].operand          # => FunctionOperand(name: "now")
+```
+
+Every node has an `accept(visitor)` method for implementing the visitor pattern.
+
+## ActiveRecord Adapter
+
+The gem includes an adapter that converts parsed JQL into ActiveRecord scopes.
+
+### Setup
+
+```ruby
+adapter = JqlRuby::Adapters::ActiveRecord.new(Issue) do |config|
+  # simple column mapping (field name defaults to column name)
+  config.field "status"
+  config.field "project", column: :project_key
+  config.field "votes"
+  config.field "created", column: :created_at
+  config.field "duedate", column: :due_date
+
+  # custom resolver for fields that need joins or complex logic
+  config.field "assignee" do |scope, operator, value|
+    case operator
+    when :eq
+      scope.joins(:assignee).where(users: { username: value })
+    when :is
+      scope.where(assignee_id: nil)
+    when :is_not
+      scope.where.not(assignee_id: nil)
+    else
+      raise JqlRuby::UnsupportedOperatorError, "assignee does not support #{operator}"
+    end
+  end
+
+  # functions resolve to a value at query time
+  config.function "currentUser" do |context|
+    context[:current_user].username
+  end
+
+  config.function "now" do |_context|
+    Time.current
+  end
+end
+```
+
+### Querying
+
+```ruby
+result = JqlRuby.parse('project = FOO AND status IN (Open, "In Progress") ORDER BY created DESC')
+scope  = adapter.apply(result.query, context: { current_user: current_user })
+# => Issue.where(project_key: "FOO").where(status: ["Open", "In Progress"]).order(created_at: :desc)
+```
+
+### Operator mapping
+
+| JQL operator | Arel method |
+|---|---|
+| `=` | `.eq` |
+| `!=` | `.not_eq` |
+| `<` / `>` / `<=` / `>=` | `.lt` / `.gt` / `.lteq` / `.gteq` |
+| `~` | `.matches` (wraps with `%`) |
+| `!~` | `.does_not_match` |
+| `IN` | `.in` |
+| `NOT IN` | `.not_in` |
+| `IS EMPTY/NULL` | `.eq(nil)` |
+| `IS NOT EMPTY/NULL` | `.not_eq(nil)` |
+
+`WAS`, `WAS NOT`, `WAS IN`, `WAS NOT IN`, and `CHANGED` raise `UnsupportedOperatorError` since they require history tables. Use a custom field resolver block to handle these for your schema.
+
+## Building Custom Adapters
+
+The adapter pattern is designed for extension. Subclass `JqlRuby::Adapters::Base` and implement six hooks:
+
+```ruby
+class MySequelAdapter < JqlRuby::Adapters::Base
+  protected
+
+  def build_scope(model)
+    # return initial dataset/scope
+  end
+
+  def apply_and(scope, scopes)
+    # combine scopes with AND
+  end
+
+  def apply_or(scope, scopes)
+    # combine scopes with OR
+  end
+
+  def apply_not(scope, inner_scope)
+    # negate a scope
+  end
+
+  def apply_terminal(scope, field_def, operator, value)
+    # apply a single field comparison
+    # field_def.column gives you the mapped column name
+  end
+
+  def apply_order(scope, field_def, direction)
+    # apply ORDER BY (direction is :asc or :desc)
+  end
+end
+```
+
+The base class handles AST traversal, field/function resolution, and operand extraction. Your adapter only needs to translate those into ORM-specific calls.
+
+## Error Handling
+
+```ruby
+result = JqlRuby.parse("invalid = = query")
+result.success?      # => false
+result.errors        # => [#<JqlRuby::ParseError ...>]
+result.errors.first.message  # => "expected value at position 10"
+result.errors.first.position # => 10
+```
+
+### Error classes
+
+| Class | Raised when |
+|---|---|
+| `JqlRuby::ParseError` | JQL syntax is invalid |
+| `JqlRuby::LexerError` | Tokenization fails (e.g. unterminated string) |
+| `JqlRuby::UnknownFieldError` | Adapter encounters an unmapped field |
+| `JqlRuby::UnknownFunctionError` | Adapter encounters an unmapped function |
+| `JqlRuby::UnsupportedOperatorError` | Adapter encounters an operator it can't handle |
+
+## Development
+
+```
+git clone https://github.com/ignitionapp/jql_ruby.git
+cd jql_ruby
+bundle install
+bundle exec rake spec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/ignitionapp/jql_ruby).
+
+1. Fork the repo
+2. Create your feature branch (`git checkout -b my-feature`)
+3. Add tests for your changes
+4. Make sure all tests pass (`bundle exec rake spec`)
+5. Commit and open a pull request
+
+## License
+
+Released under the [MIT License](LICENSE).

data/lib/jql_ruby/adapters/active_record.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module JqlRuby
+  module Adapters
+    class ActiveRecord < Base
+      protected
+
+      def build_scope(model)
+        model.all
+      end
+
+      def apply_and(_scope, scopes)
+        scopes.reduce(:merge)
+      end
+
+      def apply_or(_scope, scopes)
+        scopes.reduce(:or)
+      end
+
+      def apply_not(scope, inner_scope)
+        scope.where(inner_scope.where_clause.ast.not)
+      end
+
+      def apply_terminal(scope, field_def, operator, value)
+        column = arel_column(field_def)
+
+        predicate = case operator
+        when :eq
+          column.eq(value)
+        when :not_eq
+          column.not_eq(value)
+        when :lt
+          column.lt(value)
+        when :gt
+          column.gt(value)
+        when :lteq
+          column.lteq(value)
+        when :gteq
+          column.gteq(value)
+        when :like
+          column.matches("%#{sanitize_like(value)}%", "\\", true)
+        when :not_like
+          column.does_not_match("%#{sanitize_like(value)}%", "\\", true)
+        when :in
+          column.in(value)
+        when :not_in
+          column.not_in(value)
+        when :is
+          column.eq(nil)
+        when :is_not
+          column.not_eq(nil)
+        else
+          raise UnsupportedOperatorError, "unsupported operator: #{operator.inspect}"
+        end
+
+        scope.where(predicate)
+      end
+
+      def apply_order(scope, field_def, direction)
+        column = arel_column(field_def)
+        scope.order(column.send(direction))
+      end
+
+      private
+
+      def arel_column(field_def)
+        model.arel_table[field_def.column]
+      end
+
+      def sanitize_like(value)
+        value.to_s.gsub("\\", "\\\\\\\\").gsub("%", "\\%").gsub("_", "\\_")
+      end
+    end
+  end
+end

data/lib/jql_ruby/adapters/base.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module JqlRuby
+  module Adapters
+    class Base
+      attr_reader :model, :config
+
+      def initialize(model, &block)
+        @model = model
+        @config = Configuration.new
+        block&.call(@config)
+      end
+
+      def apply(query, context: {})
+        scope = build_scope(model)
+        scope = visit_where(scope, query.where_clause, context) if query.where_clause
+        scope = visit_order_by(scope, query.order_by, context) if query.order_by
+        scope
+      end
+
+      protected
+
+      # subclasses must override these hooks
+
+      def build_scope(_model)
+        raise NotImplementedError
+      end
+
+      def apply_and(_scope, _scopes)
+        raise NotImplementedError
+      end
+
+      def apply_or(_scope, _scopes)
+        raise NotImplementedError
+      end
+
+      def apply_not(_scope, _inner_scope)
+        raise NotImplementedError
+      end
+
+      def apply_terminal(_scope, _field_def, _operator, _value)
+        raise NotImplementedError
+      end
+
+      def apply_order(_scope, _field_def, _direction)
+        raise NotImplementedError
+      end
+
+      private
+
+      def visit_where(scope, node, context)
+        case node
+        when Ast::OrClause
+          visit_or(scope, node, context)
+        when Ast::AndClause
+          visit_and(scope, node, context)
+        when Ast::NotClause
+          visit_not(scope, node, context)
+        when Ast::TerminalClause
+          visit_terminal(scope, node, context)
+        else
+          raise AdapterError, "unexpected AST node: #{node.class}"
+        end
+      end
+
+      def visit_or(scope, node, context)
+        scopes = node.clauses.map { |clause| visit_where(build_scope(model), clause, context) }
+        apply_or(scope, scopes)
+      end
+
+      def visit_and(scope, node, context)
+        scopes = node.clauses.map { |clause| visit_where(build_scope(model), clause, context) }
+        apply_and(scope, scopes)
+      end
+
+      def visit_not(scope, node, context)
+        inner = visit_where(build_scope(model), node.clause, context)
+        apply_not(scope, inner)
+      end
+
+      def visit_terminal(scope, node, context)
+        field_name = resolve_field_name(node.field)
+        field_def = config.resolve_field(field_name)
+        operator = node.operator.value
+        value = resolve_operand(node.operand, context)
+        predicates = resolve_predicates(node.predicates, context)
+
+        if field_def.custom?
+          if field_def.resolver.arity == 4 || field_def.resolver.arity < 0
+            field_def.resolver.call(scope, operator, value, predicates)
+          else
+            field_def.resolver.call(scope, operator, value)
+          end
+        else
+          validate_operator!(operator)
+          apply_terminal(scope, field_def, operator, value)
+        end
+      end
+
+      def visit_order_by(scope, node, _context)
+        node.fields.each do |sort|
+          field_name = resolve_field_name(sort.field)
+          field_def = config.resolve_field(field_name)
+          direction = sort.direction || :asc
+          scope = apply_order(scope, field_def, direction)
+        end
+        scope
+      end
+
+      def resolve_field_name(field)
+        case field
+        when Ast::Field
+          field.name
+        when Ast::CustomField
+          "cf[#{field.id}]"
+        else
+          raise AdapterError, "unexpected field type: #{field.class}"
+        end
+      end
+
+      def resolve_operand(operand, context)
+        case operand
+        when nil
+          nil
+        when Ast::ValueOperand
+          operand.value
+        when Ast::KeywordOperand
+          nil
+        when Ast::FunctionOperand
+          config.resolve_function(operand.name, context)
+        when Ast::ListOperand
+          operand.values.map { |v| resolve_operand(v, context) }
+        else
+          raise AdapterError, "unexpected operand type: #{operand.class}"
+        end
+      end
+
+      def resolve_predicates(predicates, context)
+        predicates.map do |pred|
+          { operator: pred.operator, operand: resolve_operand(pred.operand, context) }
+        end
+      end
+
+      UNSUPPORTED_OPERATORS = %i[was was_not was_in was_not_in changed].freeze
+
+      def validate_operator!(operator)
+        if UNSUPPORTED_OPERATORS.include?(operator)
+          raise UnsupportedOperatorError,
+            "operator #{operator.inspect} requires a custom field resolver (use a block)"
+        end
+      end
+    end
+  end
+end

data/lib/jql_ruby/adapters/configuration.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module JqlRuby
+  module Adapters
+    FieldDefinition = Struct.new(:name, :column, :resolver, keyword_init: true) do
+      def custom?
+        !resolver.nil?
+      end
+    end
+
+    class Configuration
+      attr_reader :field_definitions, :function_resolvers
+
+      def initialize
+        @field_definitions = {}
+        @function_resolvers = {}
+      end
+
+      def field(name, column: nil, &block)
+        normalized = name.to_s.downcase
+        col = column || name.to_sym
+        @field_definitions[normalized] = FieldDefinition.new(
+          name: normalized,
+          column: col,
+          resolver: block
+        )
+      end
+
+      def function(name, &block)
+        normalized = name.to_s.downcase
+        @function_resolvers[normalized] = block
+      end
+
+      def resolve_field(name)
+        normalized = name.to_s.downcase
+        @field_definitions.fetch(normalized) do
+          raise UnknownFieldError, "unknown JQL field: #{name.inspect}"
+        end
+      end
+
+      def resolve_function(name, context)
+        normalized = name.to_s.downcase
+        resolver = @function_resolvers.fetch(normalized) do
+          raise UnknownFunctionError, "unknown JQL function: #{name.inspect}"
+        end
+        resolver.call(context)
+      end
+    end
+  end
+end

data/lib/jql_ruby/adapters.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "adapters/configuration"
+require_relative "adapters/base"
+require_relative "adapters/active_record"

data/lib/jql_ruby/ast/compound_clause.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module JqlRuby
+  module Ast
+    class OrClause < Node
+      attr_reader :clauses
+
+      def initialize(clauses:, **rest)
+        super(**rest)
+        @clauses = clauses
+      end
+
+      def accept(visitor)
+        visitor.visit_or_clause(self)
+      end
+    end
+
+    class AndClause < Node
+      attr_reader :clauses
+
+      def initialize(clauses:, **rest)
+        super(**rest)
+        @clauses = clauses
+      end
+
+      def accept(visitor)
+        visitor.visit_and_clause(self)
+      end
+    end
+  end
+end

data/lib/jql_ruby/ast/field.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module JqlRuby
+  module Ast
+    class Field < Node
+      attr_reader :name, :properties
+
+      def initialize(name:, properties: [], **rest)
+        super(**rest)
+        @name = name
+        @properties = properties
+      end
+
+      def accept(visitor)
+        visitor.visit_field(self)
+      end
+    end
+
+    class CustomField < Node
+      attr_reader :id, :properties
+
+      def initialize(id:, properties: [], **rest)
+        super(**rest)
+        @id = id
+        @properties = properties
+      end
+
+      def accept(visitor)
+        visitor.visit_custom_field(self)
+      end
+    end
+
+    class FieldProperty < Node
+      attr_reader :keys, :argument
+
+      def initialize(keys:, argument: nil, **rest)
+        super(**rest)
+        @keys = keys
+        @argument = argument
+      end
+
+      def accept(visitor)
+        visitor.visit_field_property(self)
+      end
+    end
+  end
+end

data/lib/jql_ruby/ast/node.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module JqlRuby
+  module Ast
+    class Node
+      attr_reader :position
+
+      def initialize(position: nil)
+        @position = position
+      end
+
+      def accept(visitor)
+        raise NotImplementedError
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && instance_variables.all? do |ivar|
+          instance_variable_get(ivar) == other.instance_variable_get(ivar)
+        end
+      end
+
+      alias_method :eql?, :==
+    end
+  end
+end

data/lib/jql_ruby/ast/not_clause.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module JqlRuby
+  module Ast
+    class NotClause < Node
+      attr_reader :clause, :operator
+
+      def initialize(clause:, operator: :not, **rest)
+        super(**rest)
+        @clause = clause
+        @operator = operator
+      end
+
+      def accept(visitor)
+        visitor.visit_not_clause(self)
+      end
+    end
+  end
+end