querylane 0.1.0

data/lib/querylane/search.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+module Querylane
+  # Runs one request: rewrite (facet toggle, chip ×) → analyze → compile →
+  # searcher → Result. Requires a server-built Scope; fails closed.
+  #
+  #   Querylane::Search.new(definition: MEMBERS, request: request, scope: scope).call
+  class Search
+    PageRequest = Data.define(:compiled, :sort, :offset, :limit)
+    # attribute: count values via the backend's facet distribution.
+    # value_filters: {value => ->(index) { Filter }} counted one by one.
+    CountRequest = Data.define(:key, :compiled, :attribute, :value_filters)
+
+    # @param definition [Querylane::Definition]
+    # @param request [Querylane::Request]
+    # @param scope [Querylane::Scope]
+    # @param context [Querylane::Context] facts for hooks (user, request)
+    def initialize(definition:, request:, scope:, context: Context.new, searcher: nil, config: Querylane.configuration)
+      raise MissingScopeError, "Pass the Querylane::Scope built for the current user" unless scope.is_a?(Scope)
+
+      @definition = definition
+      @request = request
+      @context = context
+      @scope = scope
+      @searcher = searcher
+      @config = config
+    end
+
+    # @return [Querylane::Result]
+    def call
+      @with_saved = @definition.saved_store.present?
+      started = clock
+      query = Query.analyze(@definition, @request.query, config: @config)
+      query, rewritten = rewrite(query)
+      @notice = save(query) if @request.save_search && !@scope.denied?
+      return result(:first_load, query, rewritten) if query.valid? && query.blank?
+      return result(:invalid, query, rewritten, error: query.error) unless query.valid?
+      return result(:short, query, rewritten, chips: Chips.for(query)) if query.too_short?(@definition.min_text_length)
+      return result(:denied, query, rewritten) if @scope.denied?
+
+      response = searcher.search(definition: @definition, scope: hooked_scope, page: page_request(query), counts: count_requests(query))
+      hits, merged = run_result_hooks(response.hits)
+      group_totals = group_totals_for(hits)
+      counts = response.counts
+      facets = build_facets(query, counts || {})
+      total, total_kind = total_of(response, counts)
+      state = hits.empty? ? :empty : :ok
+      instrument(state, response, started)
+      result(state, query, rewritten, hits: hits, total: total, total_kind: total_kind, page_limit: response.page_limit,
+        facets: facets, chips: Chips.for(query), timings: {total_ms: elapsed(started)}, merged: merged, group_totals: group_totals)
+    rescue SearchUnavailable
+      instrument(:unavailable, nil, started)
+      result(:unavailable, query, rewritten || false)
+    end
+
+    # Every record of one group (a GroupToken in the request), any status,
+    # within the scope and query-filter hooks. total: the group's records;
+    # shown: "index:id" of the records the page already showed (see
+    # Result#unshown_hits).
+    #
+    # @return [Querylane::Result] :unavailable when the token is invalid or expired
+    def related
+      started = clock
+      value, shown = GroupToken.read(@definition, @request.group)
+      return result(:denied, nil, false) if @scope.denied?
+      return result(:unavailable, nil, false) if value.nil? || @definition.group.nil?
+
+      group = @definition.group
+      compiled = Compiler::Compiled.new(text: nil, text_attributes: [], matching: :all,
+        filter_builder: ->(_index) { Filter.eq(group.attribute, value) })
+      response = searcher.search(definition: @definition, scope: hooked_scope,
+        page: PageRequest.new(compiled, group_sort(group), 0, group.limit), counts: [CountRequest.new(:total, compiled, nil, nil)])
+      hits, = run_result_hooks(response.hits)
+      instrument(:related, response, started)
+      result(hits.empty? ? :empty : :ok, nil, false, hits: hits, total: response.counts&.dig(:total) || response.total, shown: shown)
+    rescue SearchUnavailable
+      result(:unavailable, nil, false)
+    end
+
+    # Suggestions for the request's text: operator completions for its last
+    # word, and hits (people) for the rest. Never fails the page: a backend
+    # error leaves only the completions.
+    #
+    # @return [Querylane::Result] state :ok/:empty/:first_load/:invalid/:unavailable, with completions
+    def suggest
+      completions = Suggest.completions(@definition, @request.query)
+      whole = Query.analyze(@definition, @request.query, config: @config)
+      typed = whole.valid? ? Preview.masked(whole) : nil
+      query = Query.analyze(@definition, Suggest.people_text(@definition, @request.query), config: @config)
+      return result(:invalid, query, false, completions: completions, typed: typed) unless query.valid?
+      return result(:first_load, query, false, completions: completions, typed: typed) if query.blank? || query.too_short?(@definition.min_text_length) || @scope.denied?
+
+      started = clock
+      response = searcher.search(definition: @definition, scope: hooked_scope,
+        page: PageRequest.new(compile(query), @definition.default_sort, 0, @config.suggest_records), counts: [])
+      hits, = run_result_hooks(response.hits)
+      instrument(:suggest, response, started)
+      result(hits.empty? ? :empty : :ok, query, false, hits: hits, total: response.total, completions: completions, typed: typed)
+    rescue SearchUnavailable
+      result(:unavailable, query, false, completions: completions, typed: typed)
+    end
+
+    private
+
+    def searcher = @searcher || @config.searcher
+
+    # A group's records come back in the group's own order (default: relevance).
+    def group_sort(group)
+      group.order ? Definition::Sort.new(:group, "", group.order, false) : @definition.default_sort
+    end
+
+    # Records per group (value, down-cased) within the scope, so "more records"
+    # shows only when there are more; nil when unknown (no group, or it failed).
+    def group_totals_for(hits)
+      group = @definition.group
+      return if group.nil? || !searcher.respond_to?(:group_counts)
+
+      values = hits.filter_map { |hit| @definition.group_value(hit.document) }.uniq
+      searcher.group_counts(definition: @definition, scope: hooked_scope, attribute: group.attribute, values: values)
+    rescue SearchUnavailable
+      nil
+    end
+
+    # The required scope narrowed by every query-filter hook, per index.
+    def hooked_scope
+      hooks = @definition.hooks_for(:query_filter)
+      return @scope if hooks.empty?
+
+      extra = @scope.indexes.to_h do |index|
+        filters = hooks.map do |hook|
+          filter = guard(hook) { @definition.resolve_hook(hook).call(index: index, context: @context) }
+          raise HookError, "query_filter hook #{hook.reference} must return a Querylane::Filter" unless filter_node?(filter)
+
+          filter
+        end
+        [index, Filter.and(*filters)]
+      end
+      @scope.narrowed(extra)
+    end
+
+    # Runs results hooks in order. Each may keep a subset of the hits (in
+    # order) or merge hits into one (via contributors); never add records.
+    #
+    # @return [Array(Array<Result::Hit>, Boolean)] hits and whether any were merged away
+    def run_result_hooks(hits)
+      allowed = hits.to_h { |hit| [[hit.index, hit.id], hit] }
+      merged = false
+      @definition.hooks_for(:results).each do |hook|
+        output = guard(hook) { @definition.resolve_hook(hook).call(hits: hits.freeze, context: @context) }
+        validate_result_hook!(hook, output, allowed)
+        merged ||= hook.cardinality == :changing && output.sum { |hit| 1 + hit.contributors.size } != hits.sum { |hit| 1 + hit.contributors.size }
+        merged ||= output.any? { |hit| hit.contributors.any? }
+        hits = output
+      end
+      [hits, merged]
+    end
+
+    def validate_result_hook!(hook, output, allowed)
+      valid = output.is_a?(Array) && output.all? do |hit|
+        hit.is_a?(Result::Hit) && allowed.key?([hit.index, hit.id]) && hit.contributors.all? { |other| allowed.key?([other.index, other.id]) }
+      end
+      raise HookError, "results hook #{hook.reference} returned records it was not given" unless valid
+      raise HookError, "results hook #{hook.reference} is :preserving but changed the hits" if hook.cardinality == :preserving && output.size != output.uniq.size
+    end
+
+    def guard(hook)
+      yield
+    rescue HookError
+      raise
+    rescue => error
+      raise HookError, "#{hook.stage} hook #{hook.reference} failed (#{error.class.name})"
+    end
+
+    def filter_node?(filter)
+      filter.class.name.to_s.start_with?("Querylane::Filter::")
+    end
+
+    # :exact, :capped (at the backend's maxTotalHits; may be higher) or
+    # :estimated (counts unavailable).
+    def total_of(response, counts)
+      return [response.total, :estimated] unless counts&.key?(:total)
+
+      cap = searcher.respond_to?(:max_total_hits) ? searcher.max_total_hits : nil
+      total = counts[:total]
+      [total, (cap && total >= cap) ? :capped : :exact]
+    end
+
+    def rewrite(query)
+      return [Query.analyze(@definition, "", config: @config), query.source.present?] if @request.clear
+      # "Fix it": apply the error's correction (only an invalid query has one).
+      if @request.fix && !query.valid? && query.error.fix
+        text = Rewriter.replace(query.source, query.error.range, query.error.fix)
+        return [Query.analyze(@definition, text, config: @config), true]
+      end
+      # A saved search replaces the box whatever it holds (even an unfinished query).
+      if @request.saved
+        text = saved_text(@request.saved) || query.source
+        return [Query.analyze(@definition, text, config: @config), text != query.source]
+      end
+      return [query, false] unless rewrite_requested?(query)
+
+      text =
+        if @request.compose
+          Rewriter.compose(query, @request.compose)
+        elsif @request.toggle
+          Rewriter.toggle(query, *@request.toggle)
+        elsif @request.widen
+          Rewriter.without(query, @request.widen)
+        elsif @request.instead
+          chip_index, alternative_index = @request.instead
+          chip = Chips.for(query).find { |candidate| candidate.index == chip_index }
+          alternative = chip&.alternatives&.find { |candidate| candidate.index == alternative_index }
+          alternative ? Rewriter.replace(query.source, chip.ranges.first, alternative.text) : query.source
+        else
+          chip = Chips.for(query).find { |candidate| candidate.index == @request.remove }
+          chip ? Rewriter.remove(query.source, chip.ranges) : query.source
+        end
+      rewritten = Query.analyze(@definition, text, config: @config)
+      [rewritten, text != query.source]
+    end
+
+    # Compiles with this request's matching strategy (hits and counts agree).
+    def compile(query)
+      compiled = Compiler.compile(query)
+      @request.relax ? compiled.with(matching: :frequency) : compiled
+    end
+
+    def rewrite_requested?(query)
+      query.valid? && @request.rewriting?
+    end
+
+    def page_request(query)
+      PageRequest.new(compile(query), @request.sort, @request.offset, @request.per)
+    end
+
+    def count_requests(query)
+      requests = [CountRequest.new(:total, compile(query), nil, nil)]
+      @definition.facets.each do |facet|
+        base = Query.analyze(@definition, Rewriter.without(query, facet), config: @config)
+        next unless base.valid?
+
+        requests << facet_count_request(facet, compile(base), Rewriter.ticked(query, facet))
+      end
+      requests
+    end
+
+    def facet_count_request(facet, compiled, ticked)
+      if facet.flag
+        flags = @definition.operator(facet.flag)
+        return CountRequest.new(facet.key, compiled, flags.attribute, nil) if flags.attribute
+
+        filters = @definition.flag_values(flags, facet.values).keys.to_h { |value| [value.to_s, ->(index) { @definition.flag_filter(flags, value, index: index) }] }
+        CountRequest.new(facet.key, compiled, nil, filters)
+      else
+        operator = @definition.operator(facet.filter)
+        extra = ticked.to_h { |value| [value, ->(_index) { Filter.eq(operator.attribute, value) }] }
+        CountRequest.new(facet.key, compiled, operator.attribute, extra.presence)
+      end
+    end
+
+    def build_facets(query, counts)
+      @definition.facets.map do |facet|
+        ticked = Rewriter.ticked(query, facet)
+        found = counts[facet.key]
+        next Result::Facet.new(facet.key, facet.label, [], true, false, facet.show, facet.search) unless found
+
+        Result::Facet.new(facet.key, facet.label, facet_values(facet, found, ticked), false, truncated?(facet, found), facet.show, facet.search)
+      end
+    end
+
+    # A filter facet's distribution may be cut at the backend's
+    # maxValuesPerFacet (default 100); counts are then approximate.
+    def truncated?(facet, found)
+      facet.filter && found.size >= 100
+    end
+
+    def facet_values(facet, found, ticked)
+      if facet.flag
+        flags = @definition.operator(facet.flag)
+        @definition.flag_values(flags, facet.values).map { |value, label| Result::FacetValue.new(value.to_s, label, found.fetch(value.to_s, 0), ticked.include?(value.to_s)) }
+      else
+        top = found.sort_by { |value, count| [-count, value.to_s] }.first(facet.top).map(&:first)
+        operator = @definition.operator(facet.filter)
+        (top | ticked).map do |value|
+          label = operator.normalize ? operator.normalize.call(value) : value
+          Result::FacetValue.new(value, label, found.fetch(value, 0), ticked.include?(value))
+        end
+      end
+    end
+
+    # Saves the query through the host's store unless it holds a sensitive term.
+    #
+    # @return [Symbol, nil] :saved, :refused or :store_failed; nil when there is nothing to save
+    def save(query)
+      store = @definition.saved_searches
+      return if store.nil? || !query.valid? || query.blank?
+      return :refused if Saving.refusal(query)
+
+      store.create(context: @context, name: @request.saved_name.presence || query.source.first(80), query: query.source)
+      :saved
+    rescue => error
+      saved_store_failed(error)
+    end
+
+    def saved_text(id)
+      @definition.saved_searches&.use(context: @context, id: id)&.query
+    rescue => error
+      saved_store_failed(error)
+      nil
+    end
+
+    def saved_list
+      store = @definition.saved_searches
+      store && Array(store.all(context: @context))
+    rescue => error
+      @notice = saved_store_failed(error)
+      []
+    end
+
+    # A failing store never breaks the search; it is reported and shown as a notice.
+    def saved_store_failed(error)
+      ActiveSupport::Notifications.instrument("saved_search_failed.querylane", definition: @definition.name, error: error.class.name)
+      :store_failed
+    end
+
+    def result(state, query, rewritten, **attributes)
+      if @with_saved
+        attributes = attributes.merge(saved_searches: saved_list, notice: @notice,
+          save_refusal: (Saving.refusal(query) if query&.valid?))
+      end
+      if @request.options && query&.valid?
+        panel = Rewriter.panel(query)
+        attributes = attributes.merge(panel: panel, preview: Preview.for(@definition, query.source, panel.values, config: @config))
+      end
+      Result.new(definition: @definition, state: state, query: query&.source.to_s, request: @request, rewritten: rewritten, **attributes)
+    end
+
+    def instrument(state, response, started)
+      ActiveSupport::Notifications.instrument("search.querylane", definition: @definition.name, state: state,
+        backend_calls: response&.backend_calls, hits: response&.hits&.size, duration_ms: elapsed(started))
+    end
+
+    def clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    def elapsed(started) = ((clock - started) * 1000).round(1)
+  end
+end

data/lib/querylane/searchers/meilisearch.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Querylane
+  module Searchers
+    # Default searcher: Meilisearch 1.13+ through the meilisearch gem 0.33.x
+    # (the host adds `gem "meilisearch", "~> 0.33.0"`).
+    #
+    # Two HTTP calls per search (docs/spikes/meilisearch-1.13.md):
+    # 1. a federated multi-search for the page of hits across all indexes;
+    # 2. one batched multi-search for the exact total and every facet count
+    #    (`page: 1, hits_per_page: 0` queries, facet distributions).
+    class Meilisearch
+      HIGHLIGHT_PRE = "\u0001"
+      HIGHLIGHT_POST = "\u0002"
+      # Meilisearch's default pagination.maxTotalHits; hosts may raise it in
+      # index settings and pass `max_total_hits:`.
+      DEFAULT_MAX_TOTAL_HITS = 1000
+
+      Response = Data.define(:hits, :total, :counts, :page_limit, :backend_calls)
+
+      # @param client [Meilisearch::Client, #call] a client, or a callable returning one
+      # @param max_total_hits [Integer] the indexes' pagination.maxTotalHits
+      def initialize(client:, max_total_hits: DEFAULT_MAX_TOTAL_HITS)
+        require_gem!
+        @client = client
+        @max_total_hits = max_total_hits
+      end
+
+      # @return [Response]
+      # @return [Response] counts is nil when the count batch failed (hits kept)
+      def search(definition:, scope:, page:, counts:)
+        indexes = searchable_indexes(definition, scope, page.compiled)
+        return Response.new([], 0, empty_counts(counts), 0, 0) if indexes.empty?
+
+        hits_response = call { client.multi_search(queries: page_queries(definition, scope, page, indexes), federation: {offset: page.offset, limit: page.limit}) }
+        counts_read = count_batch(definition, scope, counts, indexes)
+        Response.new(hits(hits_response, indexes), hits_response["estimatedTotalHits"].to_i, counts_read,
+          (@max_total_hits / page.limit.to_f).ceil, counts_read ? 2 : 1)
+      end
+
+      # The cap Meilisearch applies to totalHits; a count equal to it may be higher.
+      attr_reader :max_total_hits
+
+      # How many records each group has within the scope: one facet count per
+      # index on the group attribute, filtered to the page's group values.
+      #
+      # @param values [Array<String>] the group values on the page
+      # @return [Hash{String => Integer}] keyed by the value, down-cased
+      def group_counts(definition:, scope:, attribute:, values:)
+        return {} if values.empty?
+
+        indexes = scope.indexes.each_with_object({}) do |key, found|
+          found[definition.index_name(key)] = key unless scope.filter_for(key).is_a?(Filter::Nothing)
+        end
+        return {} if indexes.empty?
+
+        queries = indexes.map do |name, key|
+          filter = Filter.and(scope.filter_for(key), Filter.in(attribute, values))
+          {index_uid: name, q: "", filter: Expression.render(filter), facets: [attribute.to_s], page: 1, hits_per_page: 0}
+        end
+        call { client.multi_search(queries: queries) }.fetch("results").each_with_object(Hash.new(0)) do |answer, totals|
+          answer.fetch("facetDistribution", {}).fetch(attribute.to_s, {}).each { |value, count| totals[value.to_s.downcase] += count }
+        end
+      end
+
+      private
+
+      def client = @client.respond_to?(:call) ? @client.call : @client
+
+      def call
+        yield
+      rescue ::Meilisearch::ApiError, ::Meilisearch::CommunicationError, ::Meilisearch::TimeoutError => error
+        raise SearchUnavailable, "Meilisearch #{error.class.name.demodulize}"
+      end
+
+      # Indexes whose scope and query can match something; the others are
+      # never sent (a Nothing scope must not turn into an unrestricted query).
+      def searchable_indexes(definition, scope, compiled)
+        scope.indexes.each_with_object({}) do |key, indexes|
+          next if Filter.and(scope.filter_for(key), compiled.filter_for(key)).is_a?(Filter::Nothing)
+
+          indexes[definition.index_name(key)] = key
+        end
+      end
+
+      def empty_counts(counts)
+        counts.to_h { |count| [count.key, (count.key == :total) ? 0 : {}] }
+      end
+
+      # Exact totals and facet counts; nil if the batch fails (hits are kept).
+      def count_batch(definition, scope, counts, indexes)
+        queries, readers = count_plan(definition, scope, counts, indexes)
+        return {} if queries.empty?
+
+        read_counts(readers, call { client.multi_search(queries: queries).fetch("results") })
+      rescue SearchUnavailable
+        nil
+      end
+
+      def require_gem!
+        require "meilisearch"
+        return if Gem::Requirement.new("~> 0.33.0").satisfied_by?(Gem::Version.new(::Meilisearch::VERSION))
+
+        raise ConfigurationError, "querylane's Meilisearch searcher needs the meilisearch gem ~> 0.33.0 (found #{::Meilisearch::VERSION})"
+      rescue LoadError
+        raise ConfigurationError, "Add gem \"meilisearch\", \"~> 0.33.0\" to use Querylane::Searchers::Meilisearch"
+      end
+
+      def base_query(name, key, scope, compiled)
+        query = {index_uid: name, q: compiled.text.to_s, matching_strategy: compiled.matching.to_s}
+        query[:attributes_to_search_on] = compiled.text_attributes if compiled.text
+        combined = Filter.and(scope.filter_for(key), compiled.filter_for(key))
+        filter = Expression.render(combined) unless combined.is_a?(Filter::Nothing)
+        query[:filter] = filter if filter
+        query
+      end
+
+      def page_queries(definition, scope, page, indexes)
+        indexes.map do |name, key|
+          query = base_query(name, key, scope, page.compiled).merge(
+            attributes_to_highlight: definition.highlight, highlight_pre_tag: HIGHLIGHT_PRE, highlight_post_tag: HIGHLIGHT_POST,
+            show_ranking_score_details: true
+          )
+          query[:attributes_to_retrieve] = definition.retrieve if definition.retrieve
+          query[:sort] = page.sort.by.map { |attribute, direction| "#{attribute}:#{direction}" } if page.sort&.by
+          query
+        end
+      end
+
+      # Builds the count queries and, for each, how to read its answer.
+      def count_plan(definition, scope, counts, indexes)
+        queries = []
+        readers = []
+        counts.each do |count|
+          indexes.each do |name, key|
+            base = base_query(name, key, scope, count.compiled).merge(page: 1, hits_per_page: 0)
+            if count.attribute.nil? && count.value_filters.nil?
+              queries << base
+              readers << [count.key, :total, nil]
+            end
+            if count.attribute
+              queries << base.merge(facets: [count.attribute])
+              readers << [count.key, :distribution, count.attribute]
+            end
+            count.value_filters&.each do |value, filter|
+              combined = Filter.and(scope.filter_for(key), count.compiled.filter_for(key), filter.call(key))
+              next if combined.is_a?(Filter::Nothing)
+
+              queries << base.merge(filter: Expression.render(combined)).compact
+              readers << [count.key, :value, value]
+            end
+          end
+        end
+        [queries, readers]
+      end
+
+      # Sums each count across indexes. Explicit per-value counts replace the
+      # distribution's number for that value (they are exact for ticked values
+      # outside the distribution's top values).
+      def read_counts(readers, results)
+        counts = {}
+        explicit = Hash.new { |hash, key| hash[key] = Hash.new(0) }
+        readers.each_with_index do |(key, kind, detail), position|
+          answer = results.fetch(position)
+          case kind
+          when :total then counts[key] = counts.fetch(key, 0) + answer["totalHits"].to_i
+          when :distribution
+            bucket = counts[key] ||= Hash.new(0)
+            answer.fetch("facetDistribution", {}).fetch(detail, {}).each { |value, number| bucket[value.to_s] += number }
+          when :value then explicit[key][detail] += answer["totalHits"].to_i
+          end
+        end
+        explicit.each do |key, values|
+          bucket = counts[key] ||= Hash.new(0)
+          values.each { |value, number| bucket[value] = number unless bucket.key?(value) }
+        end
+        counts
+      end
+
+      def hits(response, indexes)
+        response.fetch("hits").map do |hit|
+          index = indexes.fetch(hit.dig("_federation", "indexUid"))
+          document = hit.reject { |key, _| key.start_with?("_") }
+          Result::Hit.new(index: index, id: document["id"].to_s, document: document, formatted: hit["_formatted"] || {},
+            ranking_details: hit["_rankingScoreDetails"] || {})
+        end
+      end
+
+      # Renders a Querylane::Filter as a Meilisearch filter expression.
+      module Expression
+        module_function
+
+        # @return [String, nil] nil when the filter matches everything
+        def render(filter)
+          case filter
+          when Filter::Everything, nil then nil
+          when Filter::Nothing then raise ArgumentError, "Nothing filters are never sent; the index is skipped"
+          when Filter::Raw then filter.expression
+          when Filter::Eq then "#{filter.attribute} = #{value(filter.value)}"
+          when Filter::In then "#{filter.attribute} IN [#{filter.values.map { |item| value(item) }.join(", ")}]"
+          when Filter::Null then "#{filter.attribute} IS NULL"
+          when Filter::Missing then "#{filter.attribute} NOT EXISTS"
+          when Filter::Not then "NOT (#{render(filter.filter)})"
+          when Filter::And then join(filter.filters, "AND")
+          when Filter::Or then join(filter.filters, "OR")
+          else raise ArgumentError, "Unknown filter #{filter.class}"
+          end
+        end
+
+        def join(filters, operator)
+          parts = filters.filter_map { |part| render(part) }
+          return nil if parts.empty? && operator == "AND"
+
+          parts.map { |part| "(#{part})" }.join(" #{operator} ")
+        end
+
+        def value(item)
+          case item
+          when true, false, Numeric then item.to_s
+          else "'#{item.to_s.gsub("\\") { "\\\\" }.gsub("'") { "\\'" }}'"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/querylane/suggest.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Querylane
+  # Suggestions for the last word of a query (header box and palette):
+  # operator names it starts ("pol" → policy:) and flag values after a key
+  # ("is:" → is:active). The rest of the text is what people are searched by.
+  module Suggest
+    # word: replaces the query's last word (the page never repeats the query).
+    Completion = Data.define(:word, :hint)
+
+    module_function
+
+    # @param definition [Querylane::Definition]
+    # @param text [String] the box text
+    # @return [Array<Completion>]
+    def completions(definition, text)
+      word = split(text).last
+      return [] if word.empty? || word.start_with?("-", "(", '"')
+
+      key, partial = word.split(":", 2)
+      partial.nil? ? operator_completions(definition, word) : value_completions(definition, key, partial)
+    end
+
+    # The text people are searched by: without a trailing word that is being
+    # completed into an operator (it is not a name).
+    #
+    # @return [String]
+    def people_text(definition, text)
+      head, word = split(text)
+      (completions(definition, text).any? || word.include?(":")) ? head.rstrip : text
+    end
+
+    def split(text)
+      text = text.to_s
+      word = text[/\S*\z/]
+      [text[0, text.length - word.length], word]
+    end
+
+    def operator_completions(definition, word)
+      return [] if word.length < 2
+
+      typed = word.downcase
+      (definition.texts + definition.filters + definition.flags).filter_map do |operator|
+        keys = [operator.key, *(operator.respond_to?(:aliases) ? operator.aliases : [])].map(&:to_s)
+        next if keys.include?(typed)
+
+        key = keys.find { |candidate| candidate.start_with?(typed) }
+        Completion.new("#{key}:", hint(operator)) if key
+      end
+    end
+
+    def value_completions(definition, key, partial)
+      flags = definition.operator(key)
+      return [] unless flags.is_a?(Definition::Flags)
+
+      flags.values.select { |value, _| value.to_s.start_with?(partial.downcase) && value.to_s != partial.downcase }
+        .map { |value, label| Completion.new("#{key}:#{value}", label) }
+    end
+
+    # @return [String] a short description of an operator
+    def hint(operator)
+      return operator.label if operator.is_a?(Definition::Flags)
+
+      operator.label.gsub("%{value}", "").strip
+    end
+  end
+end

data/lib/querylane/version.rb

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