standup_md 1.0.1 → 2.0.0

data/lib/standup_md/entry_list.rb

@@ -10,15 +10,7 @@ module StandupMD
     include Enumerable
 
     ##
-    # Access to the class's configuration.
-    #
-    # @return [StandupMD::Config::EntryList]
-    def self.config
-      @config ||= StandupMD.config.entry_list
-    end
-
-    ##
-    # Contruct a list. Can pass any amount of +StandupMD::Entry+ instances.
+    # Construct a list. Can pass any amount of +StandupMD::Entry+ instances.
     #
     # @param [Entry] entries
     #
@@ -26,7 +18,6 @@ module StandupMD
     def initialize(*entries)
       entries.each { |entry| validate_entry(entry) }
 
-      @config = self.class.config
       @entries = entries
     end
 
@@ -35,7 +26,7 @@ module StandupMD
     #
     # @param [StandupMD::Entry] entry
     #
-    # @return [Array]
+    # @return [StandupMD::EntryList]
     def <<(entry)
       validate_entry(entry)
 
@@ -100,9 +91,9 @@ module StandupMD
     #
     # @param [Date] end_date
     #
-    # @return [Array]
+    # @return [StandupMD::EntryList]
     def filter!(start_date, end_date)
-      @entries = filter(start_date, end_date)
+      @entries = filter(start_date, end_date).to_a
       self
     end
 
@@ -124,18 +115,10 @@ module StandupMD
       end.to_h
     end
 
-    ##
-    # The entry list as a json object.
-    #
-    # @return [String]
-    def to_json
-      to_h.to_json
-    end
-
     # :section: Delegators
 
     ##
-    # The following are forwarded to @entries, which is the underly array of
+    # The following are forwarded to @entries, which is the underlying array of
     # entries.
     #
     # +each+:: Iterate over each entry.

data/lib/standup_md/file.rb

@@ -8,68 +8,59 @@ module StandupMD
   ##
   # Class for handling reading and writing standup files.
   class File
+    ##
+    # Raised when a standup file or directory is missing and creation is off.
+    class NotFoundError < StandardError; end
+
     class << self
       ##
       # Access to the class's configuration.
       #
-      # @return [StandupMD::Config::EntryList]
+      # @return [StandupMD::Config::File]
       def config
-        @config ||= StandupMD.config.file
+        StandupMD.config.file
       end
 
       ##
-      # Convenience method for calling File.find(file_name).load
+      # Convenience method for calling File.find(file_name).load.
       #
       # @param [String] file_name
+      # @param [StandupMD::Config::File] config
       #
       # @return [StandupMD::File]
-      def load(file_name)
-        unless ::File.directory?(config.directory)
-          raise "Dir #{config.directory} not found." unless config.create
-
-          FileUtils.mkdir_p(config.directory)
-        end
-        new(file_name).load
+      def load(file_name, config: StandupMD.config.file)
+        new(file_name, config: config).load
       end
 
       ##
       # Find standup file in directory by file name.
       #
-      # @param [String] File_naem
-      def find(file_name)
-        unless ::File.directory?(config.directory)
-          raise "Dir #{config.directory} not found." unless config.create
-
-          FileUtils.mkdir_p(config.directory)
-        end
-        file_path = ::File.join(config.directory, file_name)
-        unless ::File.file?(file_path) || config.create
-          raise "File #{file_name} not found."
-        end
-
-        new(file_name)
+      # @param [String] file_name
+      # @param [StandupMD::Config::File] config
+      #
+      # @return [StandupMD::File]
+      def find(file_name, config: StandupMD.config.file)
+        new(file_name, config: config)
       end
 
       ##
       # Find standup file in directory by Date object.
       #
       # @param [Date] date
-      def find_by_date(date)
+      # @param [StandupMD::Config::File] config
+      #
+      # @return [StandupMD::File]
+      def find_by_date(date, config: StandupMD.config.file)
         raise ArgumentError, "Must be a Date object" unless date.is_a?(Date)
 
-        unless ::File.directory?(config.directory)
-          raise "Dir #{config.directory} not found." unless config.create
-
-          FileUtils.mkdir_p(config.directory)
-        end
-        find(date.strftime(config.name_format))
+        find(date.strftime(config.name_format), config: config)
       end
     end
 
     ##
     # The list of entries in the file.
     #
-    # @return [StandupMP::EntryList]
+    # @return [StandupMD::EntryList]
     attr_reader :entries
 
     ##
@@ -82,29 +73,20 @@ module StandupMD
     # Constructs the instance.
     #
     # @param [String] file_name
+    # @param [StandupMD::Config::File] config
     #
-    # @return [StandupMP::File]
-    def initialize(file_name)
-      @config = self.class.config
+    # @return [StandupMD::File]
+    def initialize(file_name, config: StandupMD.config.file)
+      @config = config
       @parser = StandupMD::Parsers::Markdown.new(@config)
       if file_name.include?(::File::SEPARATOR)
         raise ArgumentError,
-          "#{file_name} contains directory. Please use `StandupMD.config.file.directory=`"
-      end
-
-      unless ::File.directory?(@config.directory)
-        raise "Dir #{@config.directory} not found." unless @config.create
-
-        FileUtils.mkdir_p(@config.directory)
+          "#{file_name} contains directory. Configure the file directory separately."
       end
 
+      ensure_directory
       @name = ::File.expand_path(::File.join(@config.directory, file_name))
-
-      unless ::File.file?(@name)
-        raise "File #{@name} not found." unless @config.create
-
-        FileUtils.touch(@name)
-      end
+      ensure_file
 
       @new = ::File.zero?(@name)
       @loaded = false
@@ -137,28 +119,49 @@ module StandupMD
     ##
     # Loads the file's contents.
     #
-    # @return [StandupMD::FileList]
+    # @return [StandupMD::File]
     def load
-      raise "File #{name} does not exist." unless ::File.file?(name)
+      raise NotFoundError, "File #{name} does not exist." unless ::File.file?(name)
 
       @loaded = true
-      @entries = @parser.read(name)
+      @entries = @parser.parse(::File.read(name))
       self
     end
 
     ##
-    # Writes a new entry to the file if the first entry in the file isn't today.
-    # This method is destructive; if a file for entries in the date range
-    # already exists, it will be clobbered with the entries in the range.
+    # Writes entries to disk. This method is destructive; existing file contents
+    # are replaced by the rendered entries in the requested date range.
     #
     # @param [Hash] {start_date: Date, end_date: Date}
     #
     # @return [Boolean] true if successful
     def write(**dates)
+      raise ArgumentError, "No entries loaded for #{name}" if entries.nil? || entries.empty?
+
       sorted_entries = entries.sort
       start_date = dates.fetch(:start_date, sorted_entries.first.date)
       end_date = dates.fetch(:end_date, sorted_entries.last.date)
-      @parser.write(name, sorted_entries, start_date: start_date, end_date: end_date)
+      ::File.write(
+        name,
+        @parser.render(sorted_entries, start_date: start_date, end_date: end_date)
+      )
+      true
+    end
+
+    private
+
+    def ensure_directory
+      return if ::File.directory?(@config.directory)
+      raise NotFoundError, "Dir #{@config.directory} not found." unless @config.create
+
+      FileUtils.mkdir_p(@config.directory)
+    end
+
+    def ensure_file
+      return if ::File.file?(@name)
+      raise NotFoundError, "File #{@name} not found." unless @config.create
+
+      FileUtils.touch(@name)
     end
   end
 end

data/lib/standup_md/parsers/markdown.rb

@@ -5,7 +5,6 @@ require "standup_md/entry"
 require "standup_md/entry_list"
 require "standup_md/section"
 require "standup_md/task"
-require "standup_md/title"
 
 module StandupMD
   ##
@@ -14,6 +13,10 @@ module StandupMD
     ##
     # Parser and renderer for the markdown standup format.
     class Markdown
+      ##
+      # Raised when markdown cannot be parsed into standup entries.
+      class Error < StandardError; end
+
       ##
       # Access to file configuration.
       #
@@ -29,17 +32,17 @@ module StandupMD
       end
 
       ##
-      # Reads entries from a markdown standup file.
+      # Parses entries from markdown text.
       #
-      # @param [String] file_name
+      # @param [String] text
       #
       # @return [StandupMD::EntryList]
-      def read(file_name)
+      def parse(text)
         entry_list = EntryList.new
         record = nil
         section = nil
 
-        ::File.foreach(file_name) do |line|
+        text.to_s.each_line do |line|
           line.chomp!
           next if line.strip.empty?
 
@@ -59,42 +62,40 @@ module StandupMD
         entry_list << entry(record) if record
         entry_list.sort
       rescue => e
-        raise "File malformation: #{e}"
+        raise Error, "Markdown malformation: #{e.message}"
       end
 
       ##
-      # Writes entries to a markdown standup file.
+      # Renders entries as markdown text.
       #
-      # @param [String] file_name
       # @param [StandupMD::EntryList] entries
       # @param [Date] start_date
       # @param [Date] end_date
       #
-      # @return [Boolean]
-      def write(file_name, entries, start_date:, end_date:)
-        ::File.open(file_name, "w") do |f|
-          entries.filter(start_date, end_date).sort_reverse.each do |entry|
-            f.puts Title.new(entry.date).to_markdown
-            config.sub_header_order.each do |attr|
-              section = Section.new(attr, entry.public_send("#{attr}_tasks"))
-              next if section.empty?
-
-              f.puts section.to_markdown
-            end
-            f.puts
-          end
-        end
-        true
+      # @return [String]
+      def render(entries, start_date:, end_date:)
+        entries.filter(start_date, end_date).sort_reverse.map do |entry|
+          render_entry(entry)
+        end.join
       end
 
       ##
-      # Renders a task as a markdown list item.
+      # Renders a single entry as markdown text.
       #
-      # @param [String, StandupMD::Task] task
+      # @param [StandupMD::Entry] entry
       #
       # @return [String]
-      def task_line(task)
-        build_task(task).to_markdown
+      def render_entry(entry)
+        lines = [entry_header(entry)]
+        config.sub_header_order.each do |type|
+          section = Section.new(type, entry.public_send("#{type}_tasks"))
+          next if section.empty?
+
+          lines << section_header(type)
+          section.tasks.each { |task| lines << task_line(task) }
+        end
+        lines << ""
+        lines.join("\n") + "\n"
       end
 
       private
@@ -123,11 +124,19 @@ module StandupMD
         Section.new(type)
       end
 
+      def entry_header(entry)
+        "#{"#" * config.header_depth} #{entry.date.strftime(config.header_date_format)}"
+      end
+
+      def section_header(type)
+        "#{"#" * config.sub_header_depth} #{config.public_send("#{type}_header")}"
+      end
+
       def section_type(line)
         sub_header = line.sub(/^\#{#{config.sub_header_depth}}\s*/, "")
         Entry::SECTION_TYPES.each do |type|
           header = config.public_send("#{type}_header")
-          return type if sub_header.include?(header)
+          return type if sub_header == header
         end
         raise "Unrecognized header [#{sub_header}]"
       end
@@ -146,6 +155,11 @@ module StandupMD
         /\A(?<indent>\s*)#{Regexp.escape(config.bullet_character)}\s*(?<text>.*)\z/
       end
 
+      def task_line(task)
+        indent = " " * config.indent_width * task.indent_level
+        "#{indent}#{config.bullet_character} #{task.text}"
+      end
+
       def entry(record)
         Entry.new(
           Date.strptime(record[:title], config.header_date_format),
@@ -159,12 +173,6 @@ module StandupMD
       def tasks(record, type)
         record[:sections].fetch(type, Section.new(type)).tasks
       end
-
-      def build_task(task)
-        return task if task.is_a?(Task)
-
-        Task.new(task)
-      end
     end
   end
 end

data/lib/standup_md/post/adapter.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module StandupMD
+  module Post
+    ##
+    # Base class for chat posting adapters.
+    class Adapter
+      ##
+      # Adapter-specific non-secret options.
+      #
+      # @return [Hash]
+      attr_reader :options
+
+      ##
+      # Creates an adapter.
+      #
+      # @param options [Hash]
+      def initialize(options = {})
+        @options = symbolize_keys(options)
+      end
+
+      ##
+      # Sends a message.
+      #
+      # @param message [StandupMD::Post::Message]
+      #
+      # @return [StandupMD::Post::Result]
+      def post(message)
+        raise NotImplementedError, "#{self.class} must implement #post"
+      end
+
+      private
+
+      def symbolize_keys(hash)
+        hash.each_with_object({}) do |(key, value), result|
+          result[key.to_sym] = value
+        end
+      end
+    end
+  end
+end

data/lib/standup_md/post/adapters/slack.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "standup_md/post/adapter"
+require "standup_md/post/result"
+
+module StandupMD
+  module Post
+    ##
+    # Namespace for built-in posting adapters.
+    module Adapters
+      ##
+      # Posts standup entries to Slack using the chat.postMessage Web API.
+      class Slack < StandupMD::Post::Adapter
+        ##
+        # Slack chat.postMessage endpoint.
+        #
+        # @return [String]
+        DEFAULT_ENDPOINT = "https://slack.com/api/chat.postMessage"
+
+        ##
+        # Environment variable used for the Slack token by default.
+        #
+        # @return [String]
+        DEFAULT_TOKEN_ENV = "STANDUP_MD_SLACK_TOKEN"
+
+        ##
+        # Sends a message to Slack.
+        #
+        # @param message [StandupMD::Post::Message]
+        #
+        # @return [StandupMD::Post::Result]
+        def post(message)
+          channel = message.channel || options[:channel]
+          token = ENV[token_env]
+          return failure(message, channel, "No Slack channel configured") if blank?(channel)
+          return failure(message, channel, "Missing Slack token in $#{token_env}") if blank?(token)
+
+          response = perform_request(channel, message.text, token)
+          parsed = parse_response(response.body)
+          return success(message, channel, response, parsed) if response.is_a?(Net::HTTPSuccess) && parsed["ok"]
+
+          failure(message, channel, error_message(response, parsed), parsed)
+        rescue => e
+          failure(message, channel, e.message)
+        end
+
+        private
+
+        def endpoint
+          options[:endpoint] || DEFAULT_ENDPOINT
+        end
+
+        def token_env
+          options[:token_env] || DEFAULT_TOKEN_ENV
+        end
+
+        def perform_request(channel, text, token)
+          uri = URI(endpoint)
+          request = Net::HTTP::Post.new(uri)
+          request["Authorization"] = "Bearer #{token}"
+          request["Content-Type"] = "application/json; charset=utf-8"
+          request["Accept"] = "application/json"
+          request.body = JSON.generate(channel: channel, text: text)
+
+          return options[:http].call(request, uri) if options[:http]
+
+          Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
+            http.request(request)
+          end
+        end
+
+        def parse_response(body)
+          JSON.parse(body.to_s)
+        rescue JSON::ParserError
+          {}
+        end
+
+        def success(message, channel, http_response, parsed)
+          StandupMD::Post::Result.success(
+            adapter: message.adapter,
+            channel: channel,
+            response: parsed.merge("code" => http_response.code)
+          )
+        end
+
+        def failure(message, channel, error, response = {})
+          StandupMD::Post::Result.failure(
+            adapter: message.adapter,
+            channel: channel,
+            error: error,
+            response: response
+          )
+        end
+
+        def error_message(http_response, parsed)
+          parsed["error"] || "Slack returned HTTP #{http_response.code}"
+        end
+
+        def blank?(value)
+          value.nil? || value.to_s.empty?
+        end
+      end
+    end
+  end
+end

data/lib/standup_md/post/message.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module StandupMD
+  module Post
+    ##
+    # A platform-neutral message to send through a posting adapter.
+    class Message
+      ##
+      # The standup entry being posted.
+      #
+      # @return [StandupMD::Entry]
+      attr_reader :entry
+
+      ##
+      # The rendered message body.
+      #
+      # @return [String]
+      attr_reader :text
+
+      ##
+      # The destination channel, room, or conversation identifier.
+      #
+      # @return [String, nil]
+      attr_reader :channel
+
+      ##
+      # The adapter name requested by the caller.
+      #
+      # @return [Symbol]
+      attr_reader :adapter
+
+      ##
+      # Builds a message for a posting adapter.
+      #
+      # @param entry [StandupMD::Entry]
+      # @param text [String]
+      # @param channel [String, nil]
+      # @param adapter [String, Symbol]
+      def initialize(entry:, text:, channel:, adapter:)
+        @entry = entry
+        @text = text.to_s
+        @channel = channel
+        @adapter = adapter.to_sym
+      end
+    end
+  end
+end

data/lib/standup_md/post/result.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module StandupMD
+  module Post
+    ##
+    # Result returned by posting adapters.
+    class Result
+      ##
+      # The adapter that handled the post.
+      #
+      # @return [Symbol]
+      attr_reader :adapter
+
+      ##
+      # The destination channel, room, or conversation identifier.
+      #
+      # @return [String, nil]
+      attr_reader :channel
+
+      ##
+      # Adapter-specific response metadata.
+      #
+      # @return [Hash]
+      attr_reader :response
+
+      ##
+      # Human-readable error message for failed posts.
+      #
+      # @return [String, nil]
+      attr_reader :error
+
+      ##
+      # Builds a posting result.
+      #
+      # @param success [Boolean]
+      # @param adapter [String, Symbol]
+      # @param channel [String, nil]
+      # @param response [Hash]
+      # @param error [String, nil]
+      def initialize(success:, adapter:, channel:, response: {}, error: nil)
+        @success = success
+        @adapter = adapter.to_sym
+        @channel = channel
+        @response = response
+        @error = error
+      end
+
+      ##
+      # Builds a successful result.
+      #
+      # @return [StandupMD::Post::Result]
+      def self.success(adapter:, channel:, response: {})
+        new(success: true, adapter: adapter, channel: channel, response: response)
+      end
+
+      ##
+      # Builds a failed result.
+      #
+      # @return [StandupMD::Post::Result]
+      def self.failure(adapter:, channel:, error:, response: {})
+        new(
+          success: false,
+          adapter: adapter,
+          channel: channel,
+          response: response,
+          error: error
+        )
+      end
+
+      ##
+      # Was the post successful?
+      #
+      # @return [Boolean]
+      def success?
+        @success
+      end
+
+      ##
+      # Did the post fail?
+      #
+      # @return [Boolean]
+      def failure?
+        !success?
+      end
+    end
+  end
+end