salad 0.0.1

data/lib/salad/console.rb

@@ -0,0 +1,503 @@
+# frozen_string_literal: true
+
+require 'salad'
+require_relative 'gem_help'
+require_relative 'bond_completer'
+
+module Salad
+  HINTS = [
+    "TAB completes service and gem names: `Salad.nas<TAB>` → Salad.nasturtium",
+    "TAB inside parens shows endpoint parameters: `Salad.inaturalist.observations(<TAB>`",
+    "Results render in `less`, press `q` to exit paged API results",
+    "Results render in `less`, press `/` to search within paged API results (n/N for next/previous match)",
+    "Results render in `less`, use vim-style navigation (j/k, gg/G, h/l) — `man less` is worth a read",
+    "See full endpoint docs: `help Salad.nasturtium.observations`",
+    "List all services: `help`",
+    "Service and gem names are interchangeable: `Salad.inaturalist` == `Salad.nasturtium`",
+    "`Salad.catalogue_of_life.*` and `Salad.col.*` auto-scope to the latest COL release (3LR)",
+    "Override the COL dataset: `Salad.col.nameusage_search(q: 'Aedes', dataset_id: 'COL25')`",
+    "`Salad.clb` and `Salad.checklistbank` search across ALL ChecklistBank datasets, not just COL",
+    "Type `hints` any time to see all tips"
+  ].freeze
+
+  def self.console
+    # Disable Readline's automatic space appending to completions
+    # Salad completions should be chainable without spaces
+    require 'readline'
+    Readline.completion_append_character = ""
+
+    Pry.config.prompt = Pry::Prompt.new(
+      'salad',
+      'Salad REPL prompt',
+      [->(*) { 'salad> ' }, ->(*) { 'salad* ' }]
+    )
+
+    # Case-insensitive prefix completion for top-level constants:
+    # `sala<TAB>` -> `Salad.`, `nast<TAB>` -> `Nasturtium.`, etc.
+    # The regex is tight (only matches strings that are actual prefixes of a
+    # known name) so unrelated lowercase input like `put<TAB>` falls through
+    # to Pry's default object/method completion.
+    Bond::M.complete(:on => Salad.completable_prefix_regex, :search => false, :action => lambda { |input|
+      prefix = input.line.downcase
+      Salad.completable_names
+        .select { |n| n.downcase.start_with?(prefix) }
+        .map { |n| "#{n}." }
+    })
+
+    # Help-prefixed variant: `help sal<TAB>` -> `help Salad`,
+    # `help nast<TAB>` -> `help nasturtium`. Completes to topics the help
+    # command actually recognizes (gem/service names and the literal 'Salad'),
+    # with no trailing dot so pressing Enter shows the help.
+    Bond::M.complete(:on => Salad.help_completable_prefix_regex, :search => false, :action => lambda { |input|
+      prefix = input.line.sub(/\Ahelp\s+/i, '').downcase
+      Salad.help_completable_names.select { |n| n.downcase.start_with?(prefix) }
+    })
+
+    # Configure Bond completion for Salad services and gems
+    # Don't match if there's already a dot (that's handled by endpoint completion)
+    salad_gem_pattern = /^(help\s+)?Salad\.(\w*)$/
+    Bond::M.complete(:on => salad_gem_pattern, :action => lambda { |input|
+      match = input.line.match(salad_gem_pattern)
+      if match
+        prefix = match[2]
+        completions = (Salad::SERVICES.keys.map(&:to_s) + Salad::GEMS)
+          .select { |g| g.start_with?(prefix) }
+
+        if input.line.start_with?('help ')
+          # No trailing dot: `help Salad.nasturtium` matches the help command's
+          # regex; `help Salad.nasturtium.` would fall through to "no help".
+          completions.map { |g| "Salad.#{g}" }
+        else
+          # Trailing dot for chaining: after `Salad.nast<TAB>`, the user almost
+          # always wants to type a method next, so put the cursor past the dot.
+          completions.map { |g| "Salad.#{g}." }
+        end
+      else
+        []
+      end
+    })
+
+    # Completion for endpoint/method names: "Salad.gem.method" or "Salad.gem .method" (with optional space)
+    # Handles cases where Pry adds a space after the gem name completion or around the dot
+    salad_endpoint_pattern = /^(help\s+)?Salad\.(\w+)\s*\.\s*(\w*)$/
+    Bond::M.complete(:on => salad_endpoint_pattern, :action => lambda { |input|
+      match = input.line.match(salad_endpoint_pattern)
+      if match
+        is_help = !match[1].nil?
+        gem_name = match[2]
+        method_prefix = match[3]
+
+        actual_gem_name = if Salad::SERVICES.key?(gem_name.to_sym)
+                            Salad::SERVICES[gem_name.to_sym]
+                          elsif Salad::GEMS.include?(gem_name)
+                            gem_name
+                          else
+                            nil
+                          end
+
+        if actual_gem_name
+          begin
+            mod = Salad.gem_module(actual_gem_name)
+            gem_sym = actual_gem_name.to_sym
+
+            if is_help
+              help_data = Salad::GEM_HELP[gem_sym]
+              if help_data&.[](:endpoints)
+                help_data[:endpoints].keys
+                  .select { |e| e.to_s.start_with?(method_prefix) }
+                  .map { |e| "Salad.#{gem_name}.#{e}" }
+              else
+                []
+              end
+            else
+              help_data = Salad::GEM_HELP[gem_sym]
+              endpoints = help_data&.[](:endpoints)&.keys&.map(&:to_s) || []
+
+              begin
+                public_methods = mod.methods(false).map(&:to_s)
+              rescue
+                public_methods = []
+              end
+
+              all_methods = (endpoints + public_methods).uniq
+                .select { |m| m.start_with?(method_prefix) }
+                .sort
+
+              all_methods.map { |m| "Salad.#{gem_name}.#{m}" }
+            end
+          rescue NameError
+            []
+          end
+        else
+          []
+        end
+      else
+        []
+      end
+    })
+
+    # Completion for raw module access: "Nasturtium.method" or "help Nasturtium.method".
+    # Pry's BondCompleter override disables default object-introspection completion,
+    # so we explicitly handle the SFG wrapper modules here.
+    module_to_gem = Salad::GEMS.each_with_object({}) do |g, h|
+      h[g.split('_').map(&:capitalize).join] = g
+    end
+    module_endpoint_pattern = /^(help\s+)?([A-Z]\w*)\s*\.\s*(\w*)$/
+    Bond::M.complete(:on => module_endpoint_pattern, :action => lambda { |input|
+      match = input.line.match(module_endpoint_pattern)
+      if match
+        is_help = !match[1].nil?
+        module_name = match[2]
+        method_prefix = match[3]
+        gem_name = module_to_gem[module_name]
+
+        if gem_name
+          help_data = Salad::GEM_HELP[gem_name.to_sym]
+          endpoints = help_data&.[](:endpoints)&.keys&.map(&:to_s) || []
+
+          if is_help
+            endpoints
+              .select { |e| e.start_with?(method_prefix) }
+              .sort
+              .map { |e| "#{module_name}.#{e}" }
+          else
+            public_methods = begin
+              Object.const_get(module_name).methods(false).map(&:to_s)
+            rescue NameError
+              []
+            end
+
+            (endpoints + public_methods).uniq
+              .select { |m| m.start_with?(method_prefix) }
+              .sort
+              .map { |m| "#{module_name}.#{m}" }
+          end
+        else
+          []
+        end
+      else
+        []
+      end
+    })
+
+    # Completion for keyword arguments inside a method call:
+    # "Salad.gem.method(" or "Salad.gem.method(prior: 1, partial"
+    # Shows only the params documented for that specific endpoint in GEM_HELP,
+    # and hides params already supplied in the current call.
+    # :search => false disables Bond's normal_search filter, which would otherwise
+    # require candidates to start with the full line (e.g. "Salad.inaturalist.observations(").
+    # We return short candidates ("taxon_id: ") so Readline replaces only the word
+    # after the "(" break-char instead of doubling the whole prefix.
+    salad_kwarg_pattern = /^Salad\.(\w+)\s*\.\s*(\w+)\s*\(([^)]*)$/
+    Bond::M.complete(:on => salad_kwarg_pattern, :search => false, :action => lambda { |input|
+      match = input.line.match(salad_kwarg_pattern)
+      if match
+        gem_name = match[1]
+        method_name = match[2]
+        inside_parens = match[3]
+
+        partial = inside_parens[/(\w*)\z/] || ''
+        prefix_in_parens = inside_parens[0...(inside_parens.length - partial.length)]
+
+        actual_gem_name = if Salad::SERVICES.key?(gem_name.to_sym)
+                            Salad::SERVICES[gem_name.to_sym]
+                          elsif Salad::GEMS.include?(gem_name)
+                            gem_name
+                          end
+
+        if actual_gem_name
+          help_data = Salad::GEM_HELP[actual_gem_name.to_sym]
+          endpoint = help_data && help_data[:endpoints] && help_data[:endpoints][method_name.to_sym]
+
+          if endpoint && endpoint[:params]
+            params = endpoint[:params].keys.map(&:to_s)
+            used = prefix_in_parens.scan(/(\w+)\s*:/).flatten
+            # Return only the param + ": " — Readline treats "(" as a word break,
+            # so the "word" being completed starts after the last "(" (or space),
+            # not at the beginning of the line. Returning a full-line candidate
+            # would cause Readline to insert it after the "(", doubling the prefix.
+            (params - used)
+              .select { |p| p.start_with?(partial) }
+              .sort
+              .map { |p| "#{p}: " }
+          else
+            []
+          end
+        else
+          []
+        end
+      else
+        []
+      end
+    })
+
+    # Same keyword-arg completion for raw module form: "Nasturtium.observations(...".
+    # Only documented params for the specific endpoint are returned, hiding ones
+    # already supplied in the current call.
+    module_kwarg_pattern = /^([A-Z]\w*)\s*\.\s*(\w+)\s*\(([^)]*)$/
+    Bond::M.complete(:on => module_kwarg_pattern, :search => false, :action => lambda { |input|
+      match = input.line.match(module_kwarg_pattern)
+      if match
+        module_name = match[1]
+        method_name = match[2]
+        inside_parens = match[3]
+        gem_name = module_to_gem[module_name]
+
+        if gem_name
+          partial = inside_parens[/(\w*)\z/] || ''
+          prefix_in_parens = inside_parens[0...(inside_parens.length - partial.length)]
+
+          help_data = Salad::GEM_HELP[gem_name.to_sym]
+          endpoint = help_data && help_data[:endpoints] && help_data[:endpoints][method_name.to_sym]
+
+          if endpoint && endpoint[:params]
+            params = endpoint[:params].keys.map(&:to_s)
+            used = prefix_in_parens.scan(/(\w+)\s*:/).flatten
+            (params - used)
+              .select { |p| p.start_with?(partial) }
+              .sort
+              .map { |p| "#{p}: " }
+          else
+            []
+          end
+        else
+          []
+        end
+      else
+        []
+      end
+    })
+
+    Pry.config.commands.create_command('help', 'Show Salad services and gem documentation') do
+      def process(*args)
+        topic = args.join(' ')
+        if args.empty? || topic == 'Salad'
+          show_salad_services_help
+        elsif !show_service_help(topic)
+          puts "\nNo Salad help available for `#{topic}`."
+          puts "Try `help` (no args) to list services, or Pry's `show-doc #{topic}` / `ls #{topic}` for object docs."
+        end
+      end
+
+      private
+
+      def show_salad_services_help
+        puts "\n=== Salad Services ==="
+        puts "Access bundled biodiversity informatics API wrappers by service name or gem name:\n"
+        service_width = Salad::SERVICES.keys.map { |s| s.to_s.length }.max
+        gem_width = Salad::SERVICES.values.map(&:length).max
+        Salad::SERVICES.sort.each do |service, gem_name|
+          mod = begin
+            Salad.gem_module(gem_name).to_s
+          rescue NameError
+            '(not loaded)'
+          end
+          printf "  Salad.%-#{service_width}s  Salad.%-#{gem_width}s  ->  %s\n", service, gem_name, mod
+        end
+        puts "\nUsage Examples:"
+        puts "  help Salad.checkerberry              # Show all endpoints (try: help Salad.check<TAB>)"
+        puts "  help Salad.checkerberry.verify       # Show specific endpoint (try: help Salad.checkerberry.v<TAB>)"
+        puts "  help gnverifier                      # Also works with service or gem name"
+        puts "\nAPI Examples:"
+        puts "  Salad.worms.record(127160)"
+        puts "  Crawlyflower.record(127160)          # Same as above"
+        puts "  Salad.inaturalist.observations(id: 1234)"
+        puts "\nTab-completion is powered by Bond and shows only Salad endpoints.\n\n"
+      end
+
+      def show_service_help(topic)
+        begin
+          # Try to match endpoint pattern: "Salad.gem_name.endpoint_name"
+          if topic =~ /^Salad\.([\w_]+)\.([\w_]+)$/
+            gem_name = Regexp.last_match(1)
+            endpoint_name = Regexp.last_match(2)
+            return show_endpoint_help(gem_name, endpoint_name)
+          end
+
+          # Try to match Salad service pattern: "Salad.service_name" or "Salad.gem_name"
+          if topic =~ /^Salad\.([\w_]+)$/
+            name = Regexp.last_match(1)
+            # Check if it's a service name, and convert to gem name
+            gem_name = Salad::SERVICES[name.to_sym] || name
+            show_gem_methods(gem_name)
+            return true
+          end
+
+          # Try matching just service or gem name: "inaturalist" or "nasturtium"
+          if Salad::SERVICES.key?(topic.to_sym)
+            gem_name = Salad::SERVICES[topic.to_sym]
+            show_gem_methods(gem_name)
+            return true
+          elsif Salad::GEMS.include?(topic)
+            show_gem_methods(topic)
+            return true
+          end
+
+          # CamelCase module form: "Nasturtium" or "Nasturtium.endpoint"
+          if topic =~ /^([A-Z]\w*)(?:\.([\w_]+))?$/
+            module_name = Regexp.last_match(1)
+            endpoint_name = Regexp.last_match(2)
+            gem_name = Salad.gem_for_module(module_name)
+            if gem_name
+              return show_endpoint_help(gem_name, endpoint_name) if endpoint_name
+              show_gem_methods(gem_name)
+              return true
+            end
+          end
+
+          false
+        rescue => e
+          puts "\nError loading help: #{e.class}: #{e.message}"
+          false
+        end
+      end
+
+      def show_gem_methods(service_or_gem)
+        mod = begin
+          Salad.gem_module(service_or_gem)
+        rescue NameError
+          puts "Service/gem '#{service_or_gem}' not found."
+          return
+        end
+
+        puts "\n=== #{mod.to_s} ==="
+
+        # Check for detailed help documentation
+        gem_sym = service_or_gem.to_sym
+        if Salad::GEM_HELP[gem_sym]
+          show_detailed_gem_help(gem_sym, mod, service_or_gem)
+        else
+          show_generic_gem_help(mod, service_or_gem)
+        end
+      end
+
+      def show_endpoint_help(gem_name, endpoint_name)
+        # Convert service name to gem name if needed
+        actual_gem_name = if Salad::SERVICES.key?(gem_name.to_sym)
+                            Salad::SERVICES[gem_name.to_sym]
+                          else
+                            gem_name
+                          end
+        gem_sym = actual_gem_name.to_sym
+
+        # Check if gem has documented help
+        unless Salad::GEM_HELP[gem_sym]
+          puts "\nNo detailed documentation available for #{gem_name}.#{endpoint_name}"
+          return true
+        end
+
+        help = Salad::GEM_HELP[gem_sym]
+        endpoints = help[:endpoints]
+
+        unless endpoints
+          puts "\nNo endpoints documented for #{gem_name}"
+          return true
+        end
+
+        endpoint_sym = endpoint_name.to_sym
+        endpoint_info = endpoints[endpoint_sym]
+
+        unless endpoint_info
+          puts "\nEndpoint '#{endpoint_name}' not found in #{gem_name}."
+          puts "\nAvailable endpoints: #{endpoints.keys.join(', ')}"
+          return true
+        end
+
+        mod = begin
+          Salad.gem_module(actual_gem_name)
+        rescue NameError
+          nil
+        end
+
+        module_name = mod ? mod.to_s : actual_gem_name.camelize
+        puts "\n=== #{module_name}.#{endpoint_name} ==="
+        puts "\n#{endpoint_info[:description]}"
+
+        if endpoint_info[:params]
+          puts "\nParameters:"
+          endpoint_info[:params].each do |param_name, param_desc|
+            puts "  #{param_name.to_s.ljust(20)} — #{param_desc}"
+          end
+        end
+
+        if endpoint_info[:examples]
+          puts "\nExamples:"
+          endpoint_info[:examples].each { |ex| puts "  #{ex}" }
+        end
+
+        puts "\n"
+        true
+      end
+
+      def show_detailed_gem_help(gem_sym, mod, gem_name)
+        help = Salad::GEM_HELP[gem_sym]
+
+        puts "\n#{help[:description]}"
+        puts "API: #{help[:api]}"
+
+        if help[:endpoints]
+          puts "\n--- Available Endpoints ---"
+          help[:endpoints].each do |endpoint_name, endpoint_info|
+            begin
+              puts "\n#{endpoint_name}"
+              puts "  #{endpoint_info[:description]}"
+
+              if endpoint_info[:examples]
+                puts "  Example: #{endpoint_info[:examples].first}"
+              end
+
+              puts "  ↳ help Salad.#{gem_name}.#{endpoint_name}  # Full documentation"
+            rescue => e
+              puts "\n#{endpoint_name}"
+              puts "  (Documentation temporarily unavailable)"
+            end
+          end
+        end
+
+        puts "\n"
+      end
+
+      def show_generic_gem_help(mod, service_or_gem)
+        # Show module methods
+        public_methods = mod.methods(false).sort
+        if public_methods.any?
+          puts "\nPublic methods:"
+          public_methods.each { |m| puts "  #{m}" }
+        end
+
+        # Show constants (often contain useful classes)
+        constants = mod.constants(false).sort
+        if constants.any?
+          puts "\nAvailable classes/constants:"
+          module_name = mod.to_s
+          constants.each { |c| puts "  #{module_name}::#{c}" }
+        end
+
+        puts "\nUsage examples:"
+        gem_name = service_or_gem.include?('_') ? service_or_gem :
+                   (Salad::SERVICES.find { |_, v| v == service_or_gem }&.last || service_or_gem)
+        module_name = mod.to_s
+        if mod.respond_to?(:help)
+          puts "  #{module_name}.help          # Gem documentation"
+        end
+        puts "  Salad.#{gem_name}.observations(...)    # Call available methods"
+        puts "  #{module_name}.observations(...)         # Or use the gem name directly"
+        puts "\n\n"
+      end
+    end
+
+    Pry.config.commands.create_command('hints', 'Show tips for using the Salad console') do
+      def process
+        puts "\n=== Salad Tips ==="
+        Salad::HINTS.each_with_index do |hint, i|
+          puts "  #{(i + 1).to_s.rjust(2)}. #{hint}"
+        end
+        puts "\n"
+      end
+    end
+
+    puts "salad v#{Salad::VERSION} — type `help` to list services, `hints` for tips."
+    puts "Tip: #{Salad::HINTS.sample}"
+    Pry.start
+  end
+end