querylane 0.1.0

data/lib/querylane/result.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Querylane
+  # Everything a page needs to render one search.
+  #
+  # state: :first_load (nothing typed), :short (words too short to search),
+  # :ok, :empty (no hits), :invalid
+  # (query error), :unavailable (backend failed; fail closed).
+  # total_kind: :exact, :capped (backend cap reached; may be higher),
+  # :estimated (counts unavailable).
+  class Result
+    # contributors: other hits a results hook merged into this one.
+    Hit = Data.define(:index, :id, :document, :formatted, :ranking_details, :contributors) do
+      def initialize(index:, id:, document:, formatted:, ranking_details:, contributors: [])
+        super
+      end
+    end
+    FacetValue = Data.define(:value, :label, :count, :ticked)
+    # show: values shown before "Find…"; search: whether the facet has a "Find…" box.
+    Facet = Data.define(:key, :label, :values, :failed, :approximate, :show, :search) do
+      def initialize(key:, label:, values:, failed:, approximate:, show: nil, search: false)
+        super
+      end
+    end
+
+    attr_reader :definition, :state, :query, :rewritten, :revision, :hits, :total, :total_kind,
+      :page, :per, :page_limit, :sort, :facets, :chips, :error, :timings, :merged, :relaxed, :panel, :preview, :shown, :completions, :typed, :saved_searches, :save_refusal, :notice, :group_totals
+
+    def initialize(definition:, state:, query:, request:, rewritten: false, hits: [], total: 0, total_kind: :exact,
+      page_limit: nil, facets: [], chips: [], error: nil, timings: {}, merged: false, panel: nil, preview: nil,
+      shown: [], completions: [], typed: nil, saved_searches: nil, save_refusal: nil, notice: nil, group_totals: nil)
+      @definition = definition
+      @state = state
+      @query = query
+      @rewritten = rewritten
+      @revision = request.revision
+      @page = request.page
+      @per = request.per
+      @sort = request.sort
+      @hits = hits
+      @total = total
+      @total_kind = total_kind
+      @page_limit = page_limit
+      @facets = facets
+      @chips = chips
+      @error = error
+      @timings = timings
+      @merged = merged
+      @relaxed = request.relax
+      @panel = panel
+      @preview = preview
+      @shown = shown
+      @completions = completions
+      # suggestions: the whole typed text, sensitive values masked (for display)
+      @typed = typed
+      # saved searches: the user's list (nil without a store), why this query
+      # cannot be saved, and a one-line notice (:saved, :refused, :store_failed)
+      @saved_searches = saved_searches
+      @save_refusal = save_refusal
+      @notice = notice
+      # records per group value (down-cased) within the scope, or nil when unknown
+      @group_totals = group_totals
+    end
+
+    # Whether the options panel is open (it needs a valid query to read).
+    def options_open? = !panel.nil?
+
+    # Facets with ticked values: an empty search can offer to widen them.
+    def widenable_facets = facets.select { |facet| facet.values.any?(&:ticked) }
+
+    def ok? = state == :ok
+
+    # Whether the query is one of the user's saved searches (the Saved star fills).
+    def saved_active? = query.present? && Array(saved_searches).any? { |saved| saved.query == query }
+
+    # A group's hits the page did not already show ("more records").
+    def unshown_hits = hits.reject { |hit| shown.include?("#{hit.index}:#{hit.id}") }
+
+    # @return [Integer]
+    def pages
+      count = (total.to_f / per).ceil
+      page_limit ? [count, page_limit].min : count
+    end
+
+    def first_shown = hits.empty? ? 0 : ((page - 1) * per) + 1
+
+    # Records shown on this page before a results hook merged any.
+    def last_shown = ((page - 1) * per) + hits.sum { |hit| 1 + hit.contributors.size }
+  end
+end

data/lib/querylane/rewriter.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module Querylane
+  # Edits query text structurally, so facets and chips never disagree with
+  # the box: the query text is the only search state.
+  #
+  # A facet value is "ticked" when the query has, at top level, a positive term
+  # for it (`is:active`) or an OR group made only of positive terms of the same
+  # operator containing it (`(policy:1 OR policy:2)`). Toggling removes every
+  # canonical occurrence of the facet and appends one canonical expression with
+  # the new value set.
+  module Rewriter
+    module_function
+
+    # @param query [Querylane::Query] valid
+    # @param facet [Querylane::Definition::Facet]
+    # @return [Array<String>] ticked values, in order of appearance
+    def ticked(query, facet)
+      occurrences(query, facet).flat_map(&:last).uniq
+    end
+
+    # @return [String] the query text with the value ticked or unticked
+    def toggle(query, facet, value)
+      value = canonical_value(query.definition, facet, value)
+      return query.source if value.nil?
+
+      current = ticked(query, facet)
+      values = current.include?(value) ? current - [value] : current + [value]
+      text = remove(query.source, occurrences(query, facet).map(&:first))
+      [text, expression(query.definition, facet, values)].reject(&:empty?).join(" ")
+    end
+
+    # The query without this facet's canonical terms (the facet's counting base).
+    #
+    # @return [String]
+    def without(query, facet)
+      remove(query.source, occurrences(query, facet).map(&:first))
+    end
+
+    # @param ranges [Array<Range>]
+    # @return [String] the text with the ranges removed; whitespace is tidied
+    #   only where a range was cut, so quoted values stay exactly as typed
+    def remove(source, ranges)
+      text = source.dup
+      ranges.sort_by(&:begin).reverse_each do |range|
+        before = text[0...range.begin].rstrip
+        after = text[range.end..].to_s.lstrip
+        text = [before, after].reject(&:empty?).join(" ")
+      end
+      text.strip
+    end
+
+    # The options panel's view of a query: each field's value (keyed by the
+    # compose field name), the parts no field can show (kept as typed), and,
+    # per masked field, the masked terms it leaves in the box (masked values
+    # never become field values, so they never reach HTML).
+    Panel = Data.define(:values, :kept, :held)
+    # One word of a field, and whether the user quoted it.
+    Token = Data.define(:text, :quoted)
+
+    # @param query [Querylane::Query] valid
+    # @return [Panel]
+    def panel(query)
+      definition = query.definition
+      used = []
+      values = {"options" => []}
+      held = {}
+      # Options first: their exact text (e.g. "-is:terminated") is not a flag value.
+      definition.panel_rows.sort_by { |row| (row.kind == :options) ? 0 : 1 }.each do |row|
+        case row.kind
+        when :options
+          row.keys.each do |key|
+            node = query.nodes.find { |candidate| !used.include?(candidate.range) && query.source[candidate.range] == definition.option(key).text }
+            next unless node
+
+            used << node.range
+            values["options"] << key.to_s
+          end
+        when :flags
+          found = occurrences_of(query, definition.operator(row.keys.first), values: row.values).reject { |pair| used.include?(pair.first) }
+          used.concat(found.map(&:first))
+          values[row.name] = found.flat_map(&:last)
+        else
+          row.keys.group_by { |key| row.bare ? row.name : key.to_s }.each do |name, keys|
+            found = keys.flat_map { |key| field_terms(query, definition.operator(key)) }.sort_by { |range, _| range.begin }
+            values[name] = ""
+            if row.masked
+              held[name] = found.map { |range, _| Preview.masked(Query.analyze(definition, query.source[range])) }.join(" ").presence
+            else
+              used.concat(found.map(&:first))
+              values[name] = found.flat_map(&:last).join(" ")
+            end
+          end
+        end
+      end
+      Panel.new(values, remove(query.source, used), held.compact)
+    end
+
+    # Rebuilds the query from options-panel fields: the parts the panel cannot
+    # show stay as typed, then each field writes its canonical text.
+    #
+    # @param fields [Hash{String => String, Array<String>}] compose field name → value
+    # @return [String]
+    def compose(query, fields)
+      definition = query.definition
+      parts = [panel(query).kept]
+      definition.panel_rows.each do |row|
+        case row.kind
+        when :options
+          chosen = Array(fields["options"]).map(&:to_s)
+          row.keys.each { |key| parts << definition.option(key).text if chosen.include?(key.to_s) }
+        when :flags
+          flag = definition.operator(row.keys.first)
+          parts << group(flag.key, Array(fields[row.name]).map(&:to_s) & definition.flag_values(flag, row.values).keys.map(&:to_s))
+        else
+          if row.bare
+            parts << tokens(fields[row.name]).map { |token| token.quoted ? quoted(token.text) : token.text }.join(" ")
+          else
+            row.keys.each { |key| parts << write(definition.operator(key), fields[key.to_s]) }
+          end
+        end
+      end
+      parts.reject(&:empty?).join(" ")
+    end
+
+    # Field text → tokens: "quoted phrases" (with \" and \\ escapes) stay one
+    # token and remember their quotes; everything else splits on spaces.
+    def tokens(value)
+      value.to_s.scan(/"((?:[^"\\]|\\.)*)"|(\S+)/).filter_map do |phrase, word|
+        phrase ? Token.new(phrase.gsub(/\\(.)/, '\1'), true) : Token.new(word, false)
+      end.reject { |token| token.text.empty? }
+    end
+
+    # One input's value as query text for its operator; quoted tokens stay quoted.
+    def write(operator, value)
+      found = tokens(value)
+      case operator
+      when Definition::Text
+        written = found.map { |token| token.quoted ? quoted(token.text) : quote(token.text) }
+        operator.default ? written.join(" ") : written.map { |text| "#{operator.key}:#{text}" }.join(" ")
+      else
+        found = found.map { |token| operator.normalize ? token.with(text: operator.normalize.call(token.text)) : token }
+        join_or(found.uniq.map { |token| "#{operator.key}:#{token.quoted ? quoted(token.text) : quote(token.text)}" })
+      end
+    end
+
+    def group(key, values)
+      join_or(values.uniq.map { |value| "#{key}:#{quote(value)}" })
+    end
+
+    def join_or(terms)
+      (terms.size > 1) ? "(#{terms.join(" OR ")})" : terms.first.to_s
+    end
+
+    # Ranges and display values (quoted as typed) of an operator's top-level
+    # terms: words for a text operator; terms or OR groups for a filter.
+    def field_terms(query, operator)
+      if operator.is_a?(Definition::Text)
+        query.text_terms.select { |term| term.operator.equal?(operator) }.map { |term| [term.range, [display(term)]] }
+      else
+        query.nodes.filter_map do |outer|
+          node = unwrap(outer)
+          if term_of?(node, operator)
+            [outer.range, [display(node)]]
+          elsif node.is_a?(Ast::Or) && node.nodes.all? { |child| term_of?(child, operator) }
+            [outer.range, node.nodes.map { |child| display(child) }]
+          end
+        end
+      end
+    end
+
+    def display(term) = term.quoted ? quoted(term.value.to_s) : term.value.to_s
+
+    # Always quoted, with " and \ escaped.
+    def quoted(value) = %("#{value.to_s.gsub(/["\\]/) { |char| "\\#{char}" }}")
+
+    # Top-level terms of an operator, alone or as an OR group of that operator
+    # only; with `values`, only those whose every value is in the list.
+    def occurrences_of(query, operator, values: nil)
+      allowed = values&.map(&:to_s)
+      found = occurrences_of_any(query, operator)
+      allowed ? found.select { |_range, found_values| (found_values - allowed).empty? } : found
+    end
+
+    def occurrences_of_any(query, operator)
+      query.nodes.filter_map do |outer|
+        node = unwrap(outer)
+        if term_of?(node, operator)
+          [outer.range, [node.value.to_s]]
+        elsif node.is_a?(Ast::Or) && node.nodes.all? { |child| term_of?(child, operator) }
+          [outer.range, node.nodes.map { |child| child.value.to_s }]
+        end
+      end
+    end
+
+    # @return [String] the text with one range replaced
+    def replace(source, range, text)
+      [source[0...range.begin], text, source[range.end..]].join
+    end
+
+    # A toggle value in the form the query would hold, or nil if invalid.
+    def canonical_value(definition, facet, value)
+      operator = operator_for(definition, facet)
+      case operator
+      when Definition::Flags
+        symbol = value.to_s.downcase.to_sym
+        definition.flag_values(operator, facet.values).key?(symbol) ? symbol.to_s : nil
+      when Definition::FilterOperator
+        normalized = operator.normalize ? operator.normalize.call(value.to_s) : value.to_s
+        (operator.format.nil? || operator.format.match?(normalized)) ? normalized : nil
+      end
+    end
+
+    # @return [Array<Array(Range, Array<String>)>]
+    def occurrences(query, facet)
+      return [] unless query.valid?
+
+      occurrences_of(query, operator_for(query.definition, facet), values: facet.values)
+    end
+
+    def expression(definition, facet, values)
+      operator = operator_for(definition, facet)
+      terms = values.map { |value| "#{operator.key}:#{quote(value)}" }
+      (terms.size > 1) ? "(#{terms.join(" OR ")})" : terms.first.to_s
+    end
+
+    def operator_for(definition, facet)
+      key = facet.flag || facet.filter
+      definition.operator(key)
+    end
+
+    # `(a OR b)` parses as a group holding one OR node; look through it.
+    def unwrap(node)
+      (node.is_a?(Ast::Group) && node.nodes.one?) ? unwrap(node.nodes.first) : node
+    end
+
+    def term_of?(node, operator)
+      node.is_a?(Query::Term) && node.operator.equal?(operator)
+    end
+
+    def quote(value)
+      value.to_s.match?(/\A[^\s()"]+\z/) ? value.to_s : quoted(value)
+    end
+  end
+end

data/lib/querylane/saving.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Querylane
+  # Saved searches: what may be saved, and the host's store.
+  #
+  # A query holding a sensitive term (typed or worked out by the interpreter,
+  # e.g. "5432" read as a last four), or any value the interpreter would read
+  # as one (a quoted "123456789", name:123456789), is never saved; the refusal
+  # offers the query without it.
+  #
+  # The store is the host's (`d.saved store: "SavedSearchStore"`): an object
+  # or class name responding to
+  #   all(context:)                → [#id, #name, #query, #used_at]
+  #   create(context:, name:, query:)
+  #   use(context:, id:)           → the saved search (and records its use), or nil
+  module Saving
+    # value: the sensitive text as shown (masked by its operator's mask);
+    # operator: what it was read as; rest: the query without sensitive terms.
+    Refusal = Data.define(:value, :operator, :rest)
+
+    module_function
+
+    # @param query [Querylane::Query] valid
+    # @return [Refusal, nil] nil when the query may be saved
+    def refusal(query)
+      definition = query.definition
+      sensitive = query.terms.filter_map do |term|
+        # A word (a name, quoted or name:) could hide an ID the box would read
+        # as sensitive; a value already given to a filter (div:0001) cannot.
+        operator = sensitive?(term.operator) ? term.operator : (term.kind == :text && reading(definition, term.value))
+        [term, operator] if operator
+      end
+      return if sensitive.empty?
+
+      term, operator = sensitive.first
+      value = Chips.mask(term.value.to_s, (operator.respond_to?(:mask) && operator.mask != :count) ? operator.mask : :all)
+      Refusal.new(value, Suggest.hint(operator), Rewriter.remove(query.source, sensitive.map { |found, _| found.range }))
+    end
+
+    def sensitive?(operator) = operator.respond_to?(:sensitive) && operator.sensitive
+
+    # The sensitive operator the interpreter would read this value as, if any.
+    def reading(definition, value)
+      key, = definition.interpret(value.to_s)
+      operator = key && definition.operator(key)
+      operator if sensitive?(operator)
+    end
+  end
+end

data/lib/querylane/scope.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Querylane
+  # What the current user may search: the logical indexes and a permission
+  # filter for each. The host builds it on the server (never from params);
+  # every hit, count and facet query ANDs the index's permission filter.
+  #
+  #   Querylane::Scope.new(employees: Querylane::Filter.in(:policy_company_id, %w[SI YI]))
+  class Scope
+    # A scope with no permission filter. Must be chosen deliberately.
+    #
+    # @param indexes [Array<Symbol>]
+    def self.unrestricted(*indexes)
+      new(indexes.flatten.to_h { |index| [index, Filter.everything] })
+    end
+
+    # The user's access could not be checked: nothing is searched and the
+    # page says so (never an unrestricted or stale answer).
+    def self.denied = Denied.new
+
+    # @param filters_by_index [Hash{Symbol => Querylane::Filter}]
+    def initialize(filters_by_index = {})
+      raise MissingScopeError, "A scope needs at least one index" if filters_by_index.blank?
+
+      @filters = filters_by_index.to_h { |index, filter| [index.to_sym, filter || raise(MissingScopeError, "No permission filter for #{index}")] }.freeze
+    end
+
+    def denied? = false
+
+    # @return [Array<Symbol>]
+    def indexes = @filters.keys
+
+    # @return [Querylane::Filter]
+    def filter_for(index) = @filters.fetch(index.to_sym)
+
+    # This scope narrowed by extra filters per index (query-filter hooks).
+    #
+    # @param extra [Hash{Symbol => Querylane::Filter}]
+    # @return [Querylane::Scope]
+    def narrowed(extra)
+      Scope.new(@filters.to_h { |index, filter| [index, Filter.and(filter, extra.fetch(index, Filter.everything))] })
+    end
+
+    # See Scope.denied.
+    class Denied < Scope
+      def initialize
+        @filters = {}.freeze
+      end
+
+      def denied? = true
+    end
+  end
+end