rita 0.1.0 → 5.0.0.alpha.1

data/lib/lita/callback.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Lita
+  # Represents the action that is taken when a route or event is triggered. It
+  # can be a block or the name of a method on object.
+  # @since 4.0.0
+  # @api private
+  class Callback
+    # A block that should be used as the callback.
+    attr_reader :block
+
+    # The name of the method in the plugin that should be called as the callback.
+    attr_reader :method_name
+
+    # @overload initialize(method_name)
+    #   @param method_name [String, Symbol] The name of the instance method that serves as the
+    #     callback.
+    # @overload initialize(callable)
+    #   @param callable [Proc] A callable object to use as the callback.
+    def initialize(method_name_or_callable)
+      if method_name_or_callable.respond_to?(:call)
+        @block = method_name_or_callable
+      else
+        @method_name = method_name_or_callable
+      end
+    end
+
+    # Invokes the callback.
+    def call(host, *args)
+      if block
+        host.instance_exec(*args, &block)
+      else
+        host.public_send(method_name, *args)
+      end
+
+      true
+    end
+  end
+end

data/lib/lita/cli.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "bundler"
+require "i18n"
+require "thor"
+
+require_relative "../lita"
+require_relative "version"
+
+module Lita
+  # The command line interface for Lita.
+  class CLI < Thor
+    include Thor::Actions
+
+    # The root file path for the templates directory.
+    # @note This is a magic method required by Thor for file operations.
+    # @return [String] The path.
+    def self.source_root
+      Lita.template_root
+    end
+
+    # Returns the full destination file path for the given file, using the supplied +default_path+
+    # as the base if run as root, otherwise falling back to the user's home directory.
+    # @param file_name [String] The name of the file.
+    # @param default_path [String] The base of the file path to use when run as root.
+    # @return [String] The full file path.
+    def self.file_path_for(file_name, default_path)
+      base_path = Process.euid.zero? ? default_path : ENV["HOME"]
+      File.join(base_path, file_name)
+    end
+
+    # Tells Thor to use a non-zero exit code on errors and silences the related deprecation warning.
+    def self.exit_on_failure?
+      true
+    end
+
+    default_task :start
+
+    desc "start", "Starts Lita"
+    option :config,
+      aliases: "-c",
+      banner: "PATH",
+      default: File.expand_path("lita_config.rb", Dir.pwd),
+      desc: "Path to the configuration file to use"
+    option :log_file,
+      aliases: "-l",
+      banner: "PATH",
+      default: file_path_for("lita.log", "/var/log"),
+      desc: "Path where the log file should be written when daemonized"
+    option :pid_file,
+      aliases: "-p",
+      banner: "PATH",
+      default: file_path_for("lita.pid", "/var/run"),
+      desc: "Path where the PID file should be written when daemonized"
+    option :kill,
+      aliases: "-k",
+      default: false,
+      desc: "Kill existing Lita processes when starting the daemon",
+      type: :boolean
+    # Starts Lita.
+    # @return [void]
+    def start
+      begin
+        Bundler.require
+      rescue Bundler::GemfileNotFound
+        say I18n.t("lita.cli.no_gemfile_warning"), :red
+        exit(false)
+      end
+
+      Lita.run(options[:config])
+    end
+
+    desc "new NAME", "Generates a new Lita project (default name: lita)"
+    # Generates a new Lita project.
+    # @param name [String] The directory name for the new project.
+    # @return [void]
+    def new(name = "lita")
+      directory "robot", name
+    end
+
+    desc "adapter NAME", "Generates a new Lita adapter"
+    # Generates a new Lita adapter.
+    # @param name [String] The name for the new adapter.
+    # @return [void]
+    def adapter(name)
+      config = generate_config(name, "adapter")
+      generate_templates(config)
+      post_messages(config)
+    end
+
+    desc "handler NAME", "Generates a new Lita handler"
+    # Generates a new Lita handler.
+    # @param name [String] The name for the new handler.
+    # @return [void]
+    def handler(name)
+      config = generate_config(name, "handler")
+      generate_templates(config)
+      post_messages(config)
+    end
+
+    desc "extension NAME", "Generates a new Lita extension"
+    # Generates a new Lita extension.
+    # @param name [String] The name for the new extension.
+    # @return [void]
+    def extension(name)
+      config = generate_config(name, "extension")
+      generate_templates(config)
+      post_messages(config)
+    end
+
+    desc "version", "Outputs the current version of Lita"
+    # Outputs the current version of Lita.
+    # @return [void]
+    def version
+      puts VERSION
+    end
+    map %w[-v --version] => :version
+
+    desc "validate", "Verifies if lita is correctly configured"
+    option :config,
+      aliases: "-c",
+      banner: "PATH",
+      default: File.expand_path("lita_config.rb", Dir.pwd),
+      desc: "Path to the configuration file to use"
+    # Outputs detailed stacktrace when there is a problem or exit 0 when OK.
+    # You can use this as a pre-check script for any automation
+    # @return [void]
+    def validate
+      begin
+        Bundler.require
+      rescue Bundler::GemfileNotFound
+        say I18n.t("lita.cli.no_gemfile_warning"), :red
+        exit(false)
+      end
+
+      Lita.load_config(options[:config])
+    end
+
+    private
+
+    def generate_config(name, plugin_type)
+      name, gem_name = normalize_names(name)
+      constant_name = name.split(/_/).map(&:capitalize).join
+      namespace = "#{plugin_type}s"
+      constant_namespace = namespace.capitalize
+      spec_type = plugin_type == "handler" ? "lita_handler" : "lita"
+      required_lita_version = Lita::VERSION.split(/\./)[0...-1].join(".")
+
+      {
+        name: name,
+        gem_name: gem_name,
+        constant_name: constant_name,
+        plugin_type: plugin_type,
+        namespace: namespace,
+        constant_namespace: constant_namespace,
+        spec_type: spec_type,
+        required_lita_version: required_lita_version
+      }.merge(generate_user_config)
+    end
+
+    def generate_user_config
+      git_user = `git config user.name`.to_s.chomp
+      git_user = "TODO: Write your name" if git_user.empty?
+      git_email = `git config user.email`.to_s.chomp
+      git_email = "TODO: Write your email address" if git_email.empty?
+
+      {
+        author: git_user,
+        email: git_email
+      }
+    end
+
+    def generate_templates(config)
+      name = config[:name]
+      gem_name = config[:gem_name]
+      namespace = config[:namespace]
+
+      target = File.join(Dir.pwd, gem_name)
+
+      template(
+        "plugin/lib/lita/plugin_type/plugin.tt",
+        "#{target}/lib/lita/#{namespace}/#{name}.rb",
+        config
+      )
+      template("plugin/lib/plugin.tt", "#{target}/lib/#{gem_name}.rb", config)
+      template(
+        "plugin/spec/lita/plugin_type/plugin_spec.tt",
+        "#{target}/spec/lita/#{namespace}/#{name}_spec.rb",
+        config
+      )
+      template("plugin/spec/spec_helper.tt", "#{target}/spec/spec_helper.rb", config)
+      template("plugin/locales/en.yml.tt", "#{target}/locales/en.yml", config)
+      if config[:plugin_type] == "handler"
+        copy_file("plugin/templates/gitkeep", "#{target}/templates/.gitkeep")
+      end
+      copy_file("plugin/Gemfile", "#{target}/Gemfile")
+      template("plugin/gemspec.tt", "#{target}/#{gem_name}.gemspec", config)
+      copy_file("plugin/gitignore", "#{target}/.gitignore")
+      copy_file("plugin/Rakefile", "#{target}/Rakefile")
+      template("plugin/README.tt", "#{target}/README.md", config)
+    end
+
+    def license_message
+      say I18n.t("lita.cli.license_notice"), :yellow
+    end
+
+    def normalize_names(name)
+      name = name.downcase.sub(/^lita[_-]/, "")
+      gem_name = "lita-#{name}"
+      name = name.tr("-", "_")
+      [name, gem_name]
+    end
+
+    def post_messages
+      license_message
+    end
+  end
+end

data/lib/lita/configurable.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "configuration_builder"
+
+module Lita
+  # Mixin to add the ability for a plugin to define configuration.
+  # @since 4.0.0
+  module Configurable
+    # A block to be executed after configuration is finalized.
+    # @return [#call, nil] The block.
+    # @since 5.0.0
+    # @api private
+    attr_accessor :after_config_block
+
+    # The plugins's {ConfigurationBuilder} object.
+    # @return [ConfigurationBuilder] The configuration builder.
+    # @since 4.0.0
+    # @api public
+    attr_accessor :configuration_builder
+
+    # Registers a block to be executed after configuration is finalized.
+    # @yieldparam config [Configuration] The handler's configuration object.
+    # @return [void]
+    # @since 5.0.0
+    def after_config(&block)
+      self.after_config_block = block
+    end
+
+    # Sets a configuration attribute on the plugin.
+    # @return [void]
+    # @since 4.0.0
+    # @see ConfigurationBuilder#config
+    def config(*args, **kwargs, &block)
+      if block
+        configuration_builder.config(*args, **kwargs, &block)
+      else
+        configuration_builder.config(*args, **kwargs)
+      end
+    end
+
+    # Initializes the configuration builder for any inheriting classes.
+    def inherited(klass)
+      super
+      klass.configuration_builder = ConfigurationBuilder.new
+    end
+  end
+end

data/lib/lita/configuration_builder.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "ice_nine"
+require "i18n"
+
+require_relative "errors"
+
+module Lita
+  # An object that stores user settings to control Lita's behavior.
+  # @since 4.0.0
+  class Configuration; end
+
+  # Provides a DSL for building {Configuration} objects.
+  # @since 4.0.0
+  class ConfigurationBuilder
+    # An array of any nested configuration builders.
+    # @return [Array<ConfigurationBuilder>] The array of child configuration builders.
+    # @api private
+    attr_reader :children
+
+    # An array of valid types for the attribute.
+    # @return [Array<Object>] The array of valid types.
+    # @api private
+    attr_reader :types
+
+    # A block used to validate the attribute.
+    # @return [Proc] The validation block.
+    # @api private
+    attr_reader :validator
+
+    # The name of the configuration attribute.
+    # @return [String, Symbol] The attribute's name.
+    # @api private
+    attr_accessor :name
+
+    # The default value of the configuration attribute.
+    # @return [Object] The attribute's default value.
+    # @api private
+    attr_reader :default_value
+
+    # A boolean indicating whether or not the attribute must be set.
+    # @return [Boolean] Whether or not the attribute is required.
+    # @api private
+    attr_accessor :required
+    alias required? required
+
+    class << self
+      # Deeply freezes a configuration object so that it can no longer be modified.
+      # @param config [Configuration] The configuration object to freeze.
+      # @return [void]
+      # @api private
+      def freeze_config(config)
+        IceNine.deep_freeze!(config)
+      end
+
+      # Loads configuration from a user configuration file.
+      # @param config_path [String] The path to the configuration file.
+      # @return [void]
+      # @api private
+      def load_user_config(config_path = nil)
+        config_path ||= "lita_config.rb"
+
+        if File.exist?(config_path)
+          begin
+            load(config_path)
+          rescue ValidationError
+            exit(false)
+          rescue StandardError => e
+            Lita.logger.fatal I18n.t(
+              "lita.config.exception",
+              message: e.message,
+              backtrace: e.backtrace.join("\n")
+            )
+            exit(false)
+          end
+        end
+      end
+    end
+
+    def initialize
+      @children = []
+      @name = :root
+    end
+
+    # Builds a {Configuration} object from the attributes defined on the builder.
+    # @param object [Configuration] The empty configuration object that will be extended to
+    #   create the final form.
+    # @return [Configuration] The fully built configuration object.
+    # @api private
+    def build(object = Configuration.new)
+      container = if children.empty?
+        build_leaf(object)
+      else
+        build_nested(object)
+      end
+
+      container.public_send(name)
+    end
+
+    # Returns a boolean indicating whether or not the attribute has any child attributes.
+    # @return [Boolean] Whether or not the attribute has any child attributes.
+    # @api private
+    def children?
+      !children.empty?
+    end
+
+    # Merges two configuration builders by making one an attribute on the other.
+    # @param name [String, Symbol] The name of the new attribute.
+    # @param attribute [ConfigurationBuilder] The configuration builder that should be its
+    #   value.
+    # @return [void]
+    # @api private
+    def combine(name, attribute)
+      attribute.name = name
+
+      children << attribute
+    end
+
+    # Declares a configuration attribute.
+    # @param name [String, Symbol] The attribute's name.
+    # @param types [Object, Array<Object>] Optional: One or more types that the attribute's value
+    #   must be.
+    # @param type [Object, Array<Object>] Optional: One or more types that the attribute's value
+    #   must be.
+    # @param required [Boolean] Whether or not this attribute must be set. If required, and Lita
+    #   is run without it set, Lita will abort on start up with a message about it.
+    # @param default [Object] An optional default value for the attribute.
+    # @yield A block to be evaluated in the context of the new attribute. Used for
+    #   defining nested configuration attributes and validators.
+    # @return [void]
+    def config(name, types: nil, type: nil, required: false, default: nil, &block)
+      attribute = self.class.new
+      attribute.name = name
+      attribute.types = types || type
+      attribute.required = required
+      attribute.default_value = default
+      attribute.instance_exec(&block) if block
+
+      children << attribute
+    end
+
+    # Sets the valid types for the configuration attribute.
+    # @param types [Object, Array<Object>] One or more valid types.
+    # @return [void]
+    # @api private
+    def types=(types)
+      @types = Array(types) if types
+    end
+
+    # Declares a block to be used to validate the value of an attribute whenever it's set.
+    # Validation blocks should return any object to indicate an error, or +nil+/+false+ if
+    # validation passed. A configuration attribute can only have one validator, so if this method
+    # is called multiple times, only the last invocation will be used as the validator.
+    # @yield The code that performs validation.
+    # @return [void]
+    def validate(&block)
+      validator = block
+
+      # Fail loudly if the default value does not satisfy the validator.
+      unless default_value.nil?
+        error = validator.call(default_value)
+        raise ValidationError, error if error
+      end
+
+      @validator = block
+    end
+
+    # Sets the default value of the attribute, raising an error if it is not among the valid types.
+    # @param value [Object] The new value of the attribute.
+    # @return [void]
+    # @raise [TypeError] If the new value is not among the declared valid types.
+    # @api private
+    def default_value=(value)
+      ensure_valid_default_value(value)
+
+      @default_value = value
+    end
+
+    private
+
+    # Finalize a nested object.
+    def build_leaf(object)
+      this = self
+      run_validator = method(:run_validator)
+      check_types = method(:check_types)
+
+      # Define the accessors.
+      object.instance_exec do
+        define_singleton_method(this.name) { instance_variable_get("@#{this.name}") }
+        define_singleton_method("#{this.name}=") do |value|
+          run_validator.call(value)
+          check_types.call(value)
+          instance_variable_set("@#{this.name}", value)
+        end
+      end
+
+      # Set the default value without triggering the attr_writer's checks.
+      object.instance_variable_set("@#{this.name}", default_value)
+
+      object
+    end
+
+    # Finalize the root builder or any builder with children.
+    def build_nested(object)
+      this = self
+
+      nested_object = Configuration.new
+      children.each { |child| child.build(nested_object) }
+      object.instance_exec { define_singleton_method(this.name) { nested_object } }
+
+      object
+    end
+
+    # Check's the value's type from inside the finalized object.
+    def check_types(value)
+      if types&.none? { |type| value.is_a?(type) }
+        Lita.logger.fatal(
+          I18n.t("lita.config.type_error", attribute: name, types: types.join(", "))
+        )
+
+        raise ValidationError
+      end
+    end
+
+    # Raise if value is non-nil and isn't one of the specified types.
+    def ensure_valid_default_value(value)
+      if !value.nil? && types&.none? { |type| value.is_a?(type) }
+        raise TypeError, I18n.t("lita.config.type_error", attribute: name, types: types.join(", "))
+      end
+    end
+
+    # Runs the validator from inside the build configuration object.
+    def run_validator(value)
+      return unless validator
+
+      error = validator.call(value)
+
+      if error
+        Lita.logger.fatal(
+          I18n.t("lita.config.validation_error", attribute: name, message: error)
+        )
+
+        raise ValidationError
+      end
+    end
+  end
+end

data/lib/lita/configuration_validator.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Lita
+  # Validates a registry's configuration, checking for required attributes that are missing.
+  # @since 4.0.0
+  # @api private
+  class ConfigurationValidator
+    # @param registry [Registry] The registry containing the configuration to validate.
+    def initialize(registry)
+      self.registry = registry
+    end
+
+    # Validates adapter and handler configuration. Logs a fatal warning and aborts if any required
+    # configuration attributes are missing.
+    # @return [void]
+    def call
+      validate_adapters
+      validate_handlers
+    end
+
+    private
+
+    # The registry containing the configuration to validate.
+    attr_accessor :registry
+
+    # The registry's adapters.
+    def adapters
+      registry.adapters
+    end
+
+    # All a plugin's top-level configuration attributes.
+    def children_for(plugin)
+      plugin.configuration_builder.children
+    end
+
+    # Return the {Configuration} for the given plugin.
+    # @param type [String, Symbol] Either "adapters" or "handlers".
+    # @param name [String, Symbol] The name of the plugin's top-level {Configuration}.
+    # @param namespace [Array<String, Symbol>] A list of nested config attributes to traverse to
+    #   find the desired {Configuration}.
+    def config_for(type, name, namespace)
+      config = registry.config.public_send(type).public_send(name)
+      namespace.each { |n| config = config.public_send(n) }
+      config
+    end
+
+    # Generates the fully qualified name of a configuration attribute.
+    def full_attribute_name(names, name)
+      (names + [name]).join(".")
+    end
+
+    # The registry's handlers.
+    def handlers
+      registry.handlers
+    end
+
+    # Validates the registry's adapters.
+    def validate_adapters
+      adapters.each do |adapter_name, adapter|
+        validate(:adapter, adapter_name, adapter, children_for(adapter))
+      end
+    end
+
+    # Validates the registry's handlers.
+    def validate_handlers
+      handlers.each do |handler|
+        validate(:handler, handler.namespace, handler, children_for(handler))
+      end
+    end
+
+    # Validates an array of attributes, recursing if any nested attributes are encountered.
+    def validate(type, plugin_name, plugin, attributes, attribute_namespace = [])
+      attributes.each do |attribute|
+        config = config_for("#{type}s", plugin_name, attribute_namespace)
+
+        if attribute.children?
+          validate(
+            type,
+            plugin_name,
+            plugin,
+            attribute.children,
+            attribute_namespace.clone.push(attribute.name),
+          )
+        elsif attribute.required? && config.public_send(attribute.name).nil?
+          Lita.logger.fatal I18n.t(
+            "lita.config.missing_required_#{type}_attribute",
+            type => plugin_name,
+            attribute: full_attribute_name(attribute_namespace, attribute.name)
+          )
+          exit(false)
+        end
+      end
+    end
+  end
+end