search-engine-for-typesense 1.0.0

data/lib/search_engine/client_options.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  # Helpers for constructing URL-level client options.
+  #
+  # These options should not appear in request bodies. They are derived from
+  # {SearchEngine.config}. This module is intentionally minimal for M0 and will
+  # be used by the client implementation in future milestones.
+  module ClientOptions
+    # Build URL-level options from configuration.
+    # @param config [SearchEngine::Config]
+    # @return [Hash] keys: :use_cache, :cache_ttl
+    def self.url_options_from_config(config = SearchEngine.config)
+      {
+        use_cache: config.use_cache ? true : false,
+        cache_ttl: Integer(config.cache_ttl_s || 0)
+      }
+    end
+  end
+end

data/lib/search_engine/collection_resolver.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require 'search_engine/registry'
+require 'search_engine/cascade'
+
+module SearchEngine
+  # Helper utilities to resolve collection models from Typesense collection names.
+  #
+  # Public API:
+  # - {.model_for_physical(physical, client: nil)} => Class or nil
+  # - {.model_for_logical(logical)} => Class or nil
+  # - {.physicals_for_logical(client, logical)} => Array<[String, Integer]>
+  module CollectionResolver
+    class << self
+      # Build a map of logical names => model classes by merging registry with
+      # a scan of the SearchEngine namespace for subclasses of Base.
+      # @return [Hash{String=>Class}]
+      def models_map
+        map = {}
+        reg = SearchEngine::Registry.mapping
+        reg.each { |k, v| map[k.to_s] = v } if reg && !reg.empty?
+
+        # Walk the SearchEngine namespace to find Base descendants
+        begin
+          SearchEngine.constants.each do |c|
+            const = SearchEngine.const_get(c)
+            next unless const.is_a?(Class)
+            next unless const.ancestors.include?(SearchEngine::Base)
+
+            logical = if const.respond_to?(:collection)
+                        const.collection.to_s
+                      else
+                        demod = const.name.split('::').last
+                        demod.respond_to?(:underscore) ? demod.underscore.pluralize : "#{demod.downcase}s"
+                      end
+            map[logical] ||= const
+          end
+        rescue StandardError
+          # best-effort; namespace may not be fully loaded
+        end
+
+        map
+      end
+
+      # Resolve a model class for a physical Typesense collection name.
+      # Tries, in order: normalized base logical, reverse alias lookup, and returns nil when not found.
+      # @param physical [#to_s]
+      # @param client [SearchEngine::Client, nil]
+      # @return [Class, nil]
+      def model_for_physical(physical, client: nil)
+        phys = physical.to_s
+        base = logical_from_physical(phys)
+
+        # Prefer models_map first to handle classes that don't invoke collection macro yet
+        mm = models_map
+        klass = mm[base]
+        klass ||= model_for_logical(base)
+        return klass if klass
+
+        # Reverse alias mapping: find a registered logical whose alias targets this physical
+        reg = SearchEngine::Registry.mapping
+        return nil if reg.nil? || reg.empty?
+
+        cli = client || SearchEngine.client
+        reg.each_key do |logical|
+          target = cli.resolve_alias(logical)
+          return reg[logical] if target && target.to_s == phys
+        rescue StandardError
+          # ignore and continue
+        end
+
+        nil
+      end
+
+      # Resolve a model class for a logical collection name using registry, falling
+      # back to autoloading a namespaced model constant.
+      # @param logical [#to_s]
+      # @return [Class, nil]
+      def model_for_logical(logical)
+        name = logical.to_s
+
+        mm = models_map
+        return mm[name] if mm.key?(name)
+
+        begin
+          return SearchEngine.collection_for(name)
+        rescue StandardError
+          # fall through
+        end
+
+        # Heuristic: SearchEngine::<Classify(name)>
+        m = classify_model(name)
+        return m if m
+
+        # Heuristic: nested modules e.g. foo_bar_baz -> SearchEngine::FooBar::Baz
+        parts = name.split('_')
+        if parts.size >= 2
+          last = parts.pop
+          mod = parts.map { |p| camelize(p) }.join
+          candidate = "SearchEngine::#{mod}::#{camelize(last)}"
+          begin
+            const = Object.const_get(candidate)
+            return const if const.is_a?(Class) && const.ancestors.include?(SearchEngine::Base)
+          rescue StandardError
+            # ignore
+          end
+        end
+
+        nil
+      end
+
+      # Convert physical name into a logical base by stripping timestamp suffix when present.
+      # @param name [#to_s]
+      # @return [String]
+      def logical_from_physical(name)
+        s = name.to_s
+        begin
+          out = SearchEngine::Cascade.normalize_physical_to_logical(s)
+          return out if out && !out.to_s.empty? && out.to_s != s
+        rescue StandardError
+          # fall through to regex fallback
+        end
+
+        # Regex fallback independent of Cascade implementation
+        m = s.match(/\A(.+)_\d{8}_\d{6}_\d{3}\z/)
+        return m[1].to_s if m && m[1]
+
+        s
+      end
+
+      # List physical collections associated with a logical alias.
+      # Prefer the alias target when present; otherwise scan server collections and
+      # group by normalized base.
+      # @param client [SearchEngine::Client]
+      # @param logical [#to_s]
+      # @return [Array<Array(String, Integer)>]
+      def physicals_for_logical(client, logical)
+        list = Array(client.list_collections)
+        pairs = list.map do |h|
+          name = (h[:name] || h['name']).to_s
+          num = (h[:num_documents] || h['num_documents']).to_i
+          [name, num]
+        end
+
+        # Filter all physicals that normalize to the logical name
+        filtered = pairs.select do |(physical, _num)|
+          logical_from_physical(physical).to_s == logical.to_s
+        end
+
+        # If no filtered physicals (unexpected), fallback to alias target if present
+        begin
+          aliased = client.resolve_alias(logical)
+          if filtered.empty? && aliased && !aliased.to_s.strip.empty?
+            # Retrieve live schema to confirm presence; if present, synthesize with count 0
+            schema = client.retrieve_collection_schema(aliased)
+            return [[aliased.to_s, (schema && (schema[:num_documents] || schema['num_documents'])).to_i]]
+          end
+        rescue StandardError
+          # ignore alias/schema issues
+        end
+
+        filtered
+      end
+
+      private
+
+      def classify_model(name)
+        if defined?(ActiveSupport::Inflector)
+          klass_name = ActiveSupport::Inflector.classify(name.to_s)
+          const = Object.const_get("SearchEngine::#{klass_name}")
+        else
+          base = name.to_s.split('_').map { |s| s[0].upcase + s[1..] }.join
+          const = Object.const_get("SearchEngine::#{base}")
+        end
+        return const if const.is_a?(Class) && const.ancestors.include?(SearchEngine::Base)
+
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def camelize(token)
+        if defined?(ActiveSupport::Inflector)
+          ActiveSupport::Inflector.camelize(token.to_s)
+        else
+          token.to_s.split('_').map { |s| s[0].upcase + s[1..] }.join
+        end
+      end
+    end
+  end
+end

data/lib/search_engine/collections_graph.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  # Build and render an in-memory graph of Typesense collections and references.
+  #
+  # Public API:
+  # - {.build(client:, style: :unicode, width: nil)} => Hash with nodes/edges and rendered ASCII
+  #
+  # The renderer produces a Unicode box-drawing diagram by default and falls
+  # back to a compact ASCII list when the layout exceeds the available width.
+  module CollectionsGraph
+    class << self
+      # Build a collections graph and produce ASCII renderings.
+      #
+      # @param client [SearchEngine::Client]
+      # @param style [Symbol] :unicode or :ascii
+      # @param width [Integer, nil] max diagram width; defaults to detected terminal width or 100
+      # @return [Hash] { nodes:, edges:, cycles:, isolated:, ascii:, ascii_compact:, stats: { ... } }
+      def build(client:, style: :unicode, width: nil)
+        safe_style = style.to_s == 'ascii' ? :ascii : :unicode
+        max_width = detect_width(width)
+
+        # Build reverse graph from Typesense (with registry fallback)
+        reverse_graph = SearchEngine::Cascade.build_reverse_graph(client: client)
+        edges = forward_edges_from_reverse(reverse_graph)
+
+        nodes, source = fetch_nodes(client, edges)
+        isolated = compute_isolated(nodes, edges)
+        cycles = detect_immediate_cycles(edges)
+
+        ascii, layout_mode = render_ascii(nodes, edges, width: max_width, style: safe_style)
+        ascii_compact = render_ascii_compact(nodes, edges, style: safe_style)
+        mermaid = render_mermaid(nodes, edges)
+
+        stats = {
+          nodes: nodes.size,
+          edges: edges.size,
+          cycles: cycles.size,
+          isolated: isolated.size,
+          layout: layout_mode,
+          source: source
+        }
+
+        if defined?(SearchEngine::Instrumentation)
+          SearchEngine::Instrumentation.instrument('search_engine.collections.graph', stats) {}
+        end
+
+        {
+          nodes: nodes,
+          edges: edges,
+          cycles: cycles,
+          isolated: isolated,
+          ascii: ascii,
+          ascii_compact: ascii_compact,
+          mermaid: mermaid,
+          stats: stats
+        }
+      end
+
+      private
+
+      # Prefer IO.console, then ENV, then stty; default to 100 when unknown.
+      def detect_width(explicit)
+        return Integer(explicit) if explicit&.to_i&.positive?
+
+        begin
+          require 'io/console'
+          w = IO.console&.winsize&.[](1)
+          return Integer(w) if w&.to_i&.positive?
+        rescue StandardError
+          # ignore; fallback paths below
+        end
+
+        env_w = ENV['COLUMNS']
+        return Integer(env_w) if env_w&.to_i&.positive?
+
+        begin
+          out = `stty size 2>/dev/null`.to_s
+          parts = out.split
+          return Integer(parts.last) if parts.size >= 2 && parts.last.to_i.positive?
+        rescue StandardError
+          # ignore
+        end
+
+        100
+      end
+
+      # Transform reverse graph (target => [{referrer, local_key, foreign_key}, ...])
+      # into a flat forward edge list.
+      def forward_edges_from_reverse(reverse_graph)
+        edges = []
+        reverse_graph.each do |target, arr|
+          Array(arr).each do |e|
+            from = (e[:referrer] || e['referrer']).to_s
+            local_key = (e[:local_key] || e['local_key']).to_s
+            foreign_key = (e[:foreign_key] || e['foreign_key']).to_s
+            to = target.to_s
+            next if from.empty? || to.empty?
+
+            edges << { from: from, to: to, local_key: local_key, foreign_key: foreign_key }
+          end
+        end
+        # Deduplicate identical edges deterministically
+        edges.uniq.sort_by { |e| [e[:from], e[:to], e[:local_key], e[:foreign_key]] }
+      end
+
+      # Determine node set from Typesense (preferred) or fallback sources.
+      def fetch_nodes(client, edges)
+        begin
+          list = Array(client.list_collections)
+          return [list.map { |c| (c[:name] || c['name']).to_s }.reject(&:empty?).uniq.sort, :typesense]
+        rescue StandardError
+          # ignore; fallback to registry/edges
+        end
+
+        if defined?(SearchEngine::Registry)
+          begin
+            reg = SearchEngine::Registry.mapping || {}
+            keys = reg.keys.map(&:to_s)
+            return [keys.uniq.sort, :registry] unless keys.empty?
+          rescue StandardError
+            # ignore
+          end
+        end
+
+        froms = edges.map { |e| e[:from] }
+        tos = edges.map { |e| e[:to] }
+        fallback = (froms + tos).uniq.sort
+        [fallback, :inferred]
+      end
+
+      def compute_isolated(nodes, edges)
+        touched = edges.flat_map { |e| [e[:from], e[:to]] }.uniq
+        (nodes - touched).sort
+      end
+
+      # Immediate cycles only: A→B and B→A pairs.
+      def detect_immediate_cycles(edges)
+        set = edges.each_with_object({}) do |e, h|
+          (h[e[:from]] ||= []) << e[:to]
+        end
+        pairs = []
+        set.each do |a, outs|
+          outs.each do |b|
+            next unless set[b]&.include?(a)
+
+            pairs << [a, b].sort
+          end
+        end
+        pairs.uniq.sort
+      end
+
+      # Render boxes-per-edge when it fits; otherwise return compact list.
+      # Returns [string, layout_mode]
+      def render_ascii(nodes, edges, width:, style: :unicode)
+        charset = charset_for(style)
+
+        header = "Collections Graph (nodes: #{nodes.size}, edges: #{edges.size})"
+
+        lines = [header, '']
+
+        # Try to render each edge as a 3-line pair of boxes with a labeled connector.
+        edges.each do |e|
+          block = build_edge_block(e, charset, width)
+          return [render_ascii_compact(nodes, edges, style: style, header: header), :compact] if block.nil?
+
+          lines.concat(block)
+        end
+
+        # Add isolated and cycles summary
+        iso = compute_isolated(nodes, edges)
+        unless iso.empty?
+          lines << ''
+          lines << "Isolated: #{iso.join(', ')}"
+        end
+
+        cycles = detect_immediate_cycles(edges)
+        lines << (cycles.empty? ? 'Cycles: none' : "Cycles: #{cycles.map { |a, b| "#{a}↔#{b}" }.join(', ')}")
+
+        [lines.join("\n"), :layered]
+      end
+
+      # Compact grouped list renderer suitable for narrow terminals.
+      def render_ascii_compact(nodes, edges, style: :unicode, header: nil)
+        charset = charset_for(style)
+        header ||= "Collections Graph (nodes: #{nodes.size}, edges: #{edges.size})"
+        lines = [header]
+
+        by_from = {}
+        edges.each do |e|
+          (by_from[e[:from]] ||= []) << e
+        end
+
+        by_from.keys.sort.each do |from|
+          lines << "- #{from}"
+          by_from[from].sort_by { |ee| [ee[:to], ee[:local_key], ee[:foreign_key]] }.each do |ee|
+            via = label_for(ee, charset, ascii_arrow: true)
+            line = if via.empty?
+                     "  #{charset[:branch]} #{charset[:arrow]} #{ee[:to]}"
+                   else
+                     "  #{charset[:branch]} #{charset[:arrow]} #{ee[:to]} [via #{via}]"
+                   end
+            lines << line
+          end
+        end
+
+        iso = compute_isolated(nodes, edges)
+        lines << "Isolated: #{iso.join(', ')}" unless iso.empty?
+
+        cycles = detect_immediate_cycles(edges)
+        lines << (cycles.empty? ? 'Cycles: none' : "Cycles: #{cycles.map { |a, b| "#{a}↔#{b}" }.join(', ')}")
+
+        lines.join("\n")
+      end
+
+      def label_for(edge, charset, ascii_arrow: false)
+        lk = edge[:local_key].to_s
+        fk = edge[:foreign_key].to_s
+        mid = ascii_arrow ? '->' : charset[:thin_arrow]
+        return '' if lk.empty? && fk.empty?
+
+        return lk if fk.empty?
+
+        return fk if lk.empty?
+
+        "#{lk} #{mid} #{fk}"
+      end
+
+      def charset_for(style)
+        if style == :ascii
+          { tl: '+', tr: '+', bl: '+', br: '+', v: '|', h: '-', arrow: '>', thin_arrow: '->', branch: '+-' }
+        else
+          { tl: '┌', tr: '┐', bl: '└', br: '┘', v: '│', h: '─', arrow: '▶', thin_arrow: '→', branch: '└─' }
+        end
+      end
+
+      # Build a single-line "boxed" label: ┌ name ┐ with balanced padding.
+      def build_single_line_box(name, charset)
+        s = name.to_s
+        inner = " #{s} "
+        charset[:tl] + inner.tr("\n", ' ') + charset[:tr]
+      end
+
+      # Build 3-line box (top, middle, bottom) for a name.
+      def build_box_lines(name, charset)
+        s = name.to_s
+        content = " #{s} "
+        top = charset[:tl] + (charset[:h] * content.length) + charset[:tr]
+        mid = charset[:v] + content + charset[:v]
+        bot = charset[:bl] + (charset[:h] * content.length) + charset[:br]
+        [top, mid, bot]
+      end
+
+      # Build the 3-line block for an edge, or nil when it does not fit width.
+      def build_edge_block(edge, charset, width)
+        lt, lm, lb = build_box_lines(edge[:from], charset)
+        rt, rm, rb = build_box_lines(edge[:to], charset)
+        label = label_for(edge, charset)
+        connector_mid = if label.empty?
+                          " #{charset[:h] * 3}#{charset[:arrow]}  "
+                        else
+                          " #{charset[:h] * 2} via #{label} #{charset[:h]}#{charset[:arrow]}  "
+                        end
+
+        total_mid = lm.length + connector_mid.length + rm.length
+        return nil if total_mid > width
+
+        gap = ' ' * connector_mid.length
+        [(lt + gap + rt), (lm + connector_mid + rm), (lb + gap + rb), '']
+      end
+
+      # Mermaid flowchart (LR) generator with labeled edges and node declarations.
+      # @return [String]
+      def render_mermaid(nodes, edges)
+        # Prefer logical names from edges to avoid physical (timestamped) names.
+        edge_names = edges.flat_map { |e| [e[:from].to_s, e[:to].to_s] }.reject(&:empty?).uniq
+        names = edge_names.empty? ? Array(nodes).map(&:to_s) : edge_names
+
+        # Stable ids for all names we intend to render.
+        ids = {}
+        names.each_with_index { |name, idx| ids[name] = sanitize_mermaid_id("C_#{idx}_#{name}") }
+
+        lines = ['flowchart LR']
+
+        # Declare nodes to ensure isolated logical nodes render as well.
+        names.each do |name|
+          id = ids[name]
+          label = name.to_s.gsub('"', '\\"')
+          lines << "  #{id}[\"#{label}\"]"
+        end
+
+        # Edges with labels (via ...), using logical names.
+        edges.each do |e|
+          from = ids[e[:from].to_s]
+          to = ids[e[:to].to_s]
+          next if from.nil? || to.nil?
+
+          via = mermaid_edge_label(e)
+          if via.empty?
+            lines << "  #{from} --> #{to}"
+          else
+            esc = via.gsub('"', '\\"')
+            lines << "  #{from} -- \"#{esc}\" --> #{to}"
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      def sanitize_mermaid_id(name)
+        s = name.to_s
+        s = s.gsub(/[^a-zA-Z0-9_]/, '_')
+        s = "C_#{s}" if s.empty? || s[0] =~ /[^a-zA-Z_]/
+        s
+      end
+
+      def mermaid_edge_label(edge)
+        lk = edge[:local_key].to_s
+        fk = edge[:foreign_key].to_s
+        return '' if lk.empty? && fk.empty?
+
+        return lk if fk.empty?
+
+        return fk if lk.empty?
+
+        "#{lk} -> #{fk}"
+      end
+    end
+  end
+end

data/lib/search_engine/compiled_params.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module SearchEngine
+  # Immutable, deterministic wrapper for compiled Typesense params.
+  #
+  # Guarantees:
+  # - Canonicalized symbol keys and lexicographic key ordering at every hash level
+  # - Array order preserved as provided
+  # - Deep frozen internal representation
+  # - Stable to_h and to_json across Ruby versions/runs
+  #
+  # Public surface mirrors a minimal read-only Hash API used in the codebase.
+  # New instances should be constructed from plain Hashes only.
+  class CompiledParams
+    EMPTY_HASH = {}.freeze
+    EMPTY_ARRAY = [].freeze
+
+    # @param value [Hash, #to_h]
+    def initialize(value)
+      input = if value.is_a?(Hash)
+                value
+              elsif value.respond_to?(:to_h)
+                value.to_h
+              else
+                EMPTY_HASH
+              end
+      @canonical = canonicalize_hash(input)
+      deep_freeze!(@canonical)
+      freeze
+    end
+
+    # Fast constructor from any object responding to +to_h+.
+    # @param value [Object]
+    # @return [SearchEngine::CompiledParams]
+    def self.from(value)
+      value.is_a?(self) ? value : new(value)
+    end
+
+    # Return the canonical, deeply frozen Hash (symbol keys, sorted order).
+    # @return [Hash]
+    def to_h
+      @canonical
+    end
+
+    # Implicit Hash conversion for APIs like Hash#merge expecting #to_hash.
+    # @return [Hash]
+    alias_method :to_hash, :to_h
+
+    # Deterministic JSON serialization using the canonical ordered Hash.
+    # @return [String]
+    def to_json(*_args)
+      JSON.generate(@canonical)
+    end
+
+    # Read-style Hash helpers used in callers ---------------------------------
+
+    # @param key [Object]
+    # @return [Object]
+    def [](key)
+      @canonical[key_to_sym(key)]
+    end
+
+    # @param key [Object]
+    # @return [Boolean]
+    def key?(key)
+      @canonical.key?(key_to_sym(key))
+    end
+
+    # @return [Array<Symbol>]
+    def keys
+      @canonical.keys
+    end
+
+    # @yieldparam key [Symbol]
+    # @yieldparam value [Object]
+    # @return [Enumerator]
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      @canonical.each(&block)
+    end
+
+    # Equality based on canonical Hash content.
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      if other.is_a?(CompiledParams)
+        other.to_h == @canonical
+      elsif other.respond_to?(:to_h)
+        other.to_h == @canonical
+      else
+        false
+      end
+    end
+
+    private
+
+    def key_to_sym(k)
+      k.respond_to?(:to_sym) ? k.to_sym : k
+    end
+
+    def canonicalize_hash(hash)
+      # Normalize keys to symbols; sort by key.to_s; recurse into values
+      sorted_keys = hash.keys.sort_by(&:to_s)
+      sorted_keys.each_with_object({}) do |k, acc|
+        sym_key = key_to_sym(k)
+        acc[sym_key] = canonicalize_value(hash[k])
+      end
+    end
+
+    def canonicalize_array(array)
+      return EMPTY_ARRAY if array.empty?
+
+      array.map { |v| canonicalize_value(v) }
+    end
+
+    def canonicalize_value(value)
+      case value
+      when Hash
+        canonicalize_hash(value)
+      when Array
+        canonicalize_array(value)
+      else
+        value
+      end
+    end
+
+    def deep_freeze!(obj)
+      case obj
+      when Hash
+        obj.each_value { |v| deep_freeze!(v) }
+        obj.freeze
+      when Array
+        obj.each { |v| deep_freeze!(v) }
+        obj.freeze
+      else
+        obj.freeze if obj.respond_to?(:freeze)
+      end
+    end
+  end
+end