timet 1.6.1.1 → 1.6.3

data/lib/timet/tag_distribution.rb

@@ -1,189 +1,210 @@
 # frozen_string_literal: true
 
+# Helper module for formatting tag distribution displays
 require_relative 'time_statistics'
-require_relative 'color_codes' # Ensure color methods are available
+require_relative 'color_codes'
+
 module Timet
-  # The TagDistribution module provides functionality to format and display the distribution of tags based on their
-  # durations. This is particularly useful for visualizing how time is distributed across different tags in a project
-  # or task management system.
-  module TagDistribution
-    MAX_BAR_LENGTH = 70
-    BLOCK_CHAR = '▅'
-    TAG_SIZE = 12
+  # Helper module for formatting tag distribution displays
+  module TagDistributionFormatting
+    module_function
 
-    # Formats and displays the tag distribution.
-    #
-    # @param duration_by_tag [Hash<String, Integer>] A hash where keys are tags and values are durations in seconds.
-    # @param colors [Hash<String, String>] A hash where keys are tags and values are color codes for display.
-    # @return [void] This method outputs the formatted tag distribution to the console.
-    #
-    # @example
-    #   duration_by_tag = { "timet" => 3600, "nextjs" => 1800 }
-    #   colors = { "timet" => "\e[31m", "nextjs" => "\e[32m" }
-    #   Formatter.format_tag_distribution(duration_by_tag, colors)
-    #   # Output:
-    #   #  \e[31m timet:   66.67%  ==================== \e[0m
-    #   #  \e[32m nextjs:   33.33%  ========== \e[0m
-    def tag_distribution(colors)
-      time_stats = TimeStatistics.new(@items)
-      total = time_stats.total_duration
+    def calculate_value_and_bar_length(duration, total)
+      value = duration.to_f / total
+      percentage_value = (value * 100).round(1)
+      bar_length = (value * TagDistribution::MAX_BAR_LENGTH).round
+      [percentage_value, bar_length]
+    end
 
-      return unless total.positive?
+    def generate_horizontal_bar(bar_length, color_index)
+      (TagDistribution::BLOCK_CHAR * bar_length).to_s.color(color_index + 1)
+    end
 
-      process_and_print_tags(time_stats, total, colors)
+    def generate_stats(tag, time_stats)
+      total_hours = (time_stats.total_duration_by_tag[tag] / 3600.0).round(1)
+      avg_minutes = (time_stats.average_by_tag[tag] / 60.0).round(1)
+      sd_minutes = (time_stats.standard_deviation_by_tag[tag] / 60).round(1)
+      "T: #{total_hours}h, AVG: #{avg_minutes}min SD: #{sd_minutes}min".gray
     end
 
-    # Processes and prints the tag distribution information.
-    #
-    # @param time_stats [Object] An object containing the time statistics, including totals and sorted durations by tag.
-    # @param total [Numeric] The total duration of all tags combined.
-    # @param colors [Object] An object containing color formatting methods.
-    # @return [void] This method outputs the tag distribution information to the standard output.
-    def process_and_print_tags(time_stats, total, colors)
-      print_summary(time_stats, total)
-      print_tags_info(time_stats, total, colors)
-      print_footer
+    def introduction(total)
+      total_hours = (total / 3600.0).round(1)
+      [
+        "\n---",
+        'Time Report Summary'.bold,
+        'This report provides a detailed breakdown of time spent ' \
+        "across various categories, totaling #{"#{total_hours}h".bold} of tracked work.".white,
+        "\n"
+      ]
     end
 
-    # Prints the footer information.
-    #
-    # @return [void] This method outputs the footer information to the standard output.
-    def print_footer
-      puts '-' * 45
-      puts 'T:'.rjust(4).red + 'The total duration'.gray
-      puts 'AVG:'.rjust(4).red + 'The average duration'.gray
-      puts 'SD:'.rjust(4).red + 'The standard deviation of the durations'.gray
+    def build_duration_part(duration)
+      total_hours = (duration / 3600.0).round(1)
+      " The cumulative time spent was #{"#{total_hours}h".bold}, " \
+        'indicating the overall effort dedicated to this area.'
     end
 
-    # Generates and prints an explanation of the time report based on tag distribution.
-    #
-    # @param time_stats [Object] An object containing the time statistics.
-    # @param total [Numeric] The total duration of all tags combined in seconds.
-    # @return [void] This method outputs the explanation to the standard output.
-    def print_explanation(time_stats, total)
-      explanations = []
-      high_sd_threshold = 0.5
-      moderate_sd_threshold = 0.2
-
-      # --- Introduction ---
-      total_duration_hours = (total / 3600.0).round(1)
-      explanations << "\n---"
-      explanations << 'Time Report Summary'.bold
-      explanations << "This report provides a detailed breakdown of time spent across various categories, totaling #{"#{total_duration_hours}h".bold} of tracked work.".white
-      explanations << "\n"
-
-      # --- Individual Category Explanations ---
-      explanations << 'Category Breakdown'.bold
-      time_stats.sorted_duration_by_tag.each do |tag, duration|
-        explanation = "#{"#{tag.capitalize}".bold}:"
-
-        # Percentage
-        percentage = (duration.to_f / total * 100).round(1)
-        explanation += " This category consumed #{"#{percentage}%".bold} of the total tracked time."
-
-        # Total Duration
-        total_hours = (duration / 3600.0).round(1)
-        explanation += " The cumulative time spent was #{"#{total_hours}h".bold}, indicating the overall effort dedicated to this area."
-
-        # Average Duration
-        avg_minutes = (time_stats.average_by_tag[tag] / 60.0).round(1)
-        explanation += " On average, each task took #{"#{avg_minutes}min".bold}, which helps in understanding the typical time commitment per task."
-
-        # Standard Deviation
-        sd_minutes = (time_stats.standard_deviation_by_tag[tag] / 60.0).round(1)
-        avg_duration_seconds = time_stats.average_by_tag[tag]
-
-        if sd_minutes > avg_duration_seconds / 60.0 * high_sd_threshold
-          explanation += " A high standard deviation of #{"#{sd_minutes}min".bold} relative to the average suggests significant variability in task durations. This could imply inconsistent task definitions, varying complexity, or frequent interruptions.".red
-        elsif sd_minutes > avg_duration_seconds / 60.0 * moderate_sd_threshold
-          explanation += " A moderate standard deviation of #{"#{sd_minutes}min".bold} indicates some variation in task durations.".blue
-        else
-          explanation += " A low standard deviation of #{"#{sd_minutes}min".bold} suggests that task durations were quite consistent and predictable.".green
-        end
+    def build_average_part(metrics)
+      " On average, each task took #{"#{metrics[:avg_minutes]}min".bold}, " \
+        'which helps in understanding the typical time commitment per task.'
+    end
+
+    def high_sd_message(sd_min)
+      " A high standard deviation of #{"#{sd_min}min".bold} " \
+      'relative to the average suggests significant variability in task durations. ' \
+      'This could imply inconsistent task definitions, varying complexity, ' \
+      'or frequent interruptions.'.red
+    end
+
+    def moderate_sd_message(sd_min)
+      " A moderate standard deviation of #{"#{sd_min}min".bold} " \
+      'indicates some variation in task durations.'.blue
+    end
+
+    def low_sd_message(sd_min)
+      " A low standard deviation of #{"#{sd_min}min".bold} " \
+      'suggests that task durations were quite consistent and predictable.'.green
+    end
+
+    def build_major_summary(major_categories)
+      total_percentage = major_categories.sum(&:last)
+      category_names = major_categories.map { |c, _| "'#{c.capitalize}'" }.join(' and ')
+      ["\nTogether, #{category_names} dominate the time spent, " \
+       "accounting for nearly #{"#{total_percentage.round}%".bold} of the total.".white]
+    end
+  end
+
+  # The TagDistribution module provides functionality to format and display
+  # the distribution of tags based on their durations.
+  module TagDistribution
+    MAX_BAR_LENGTH = 70
+    BLOCK_CHAR = '▅'
+    TAG_SIZE = 12
+
+    # Context object for tag distribution formatting
+    Context = Struct.new(:time_stats, :total, :colors) do
+      include TagDistributionFormatting
+
+      # Formats the overall average and standard deviation from the time statistics.
+      # @return [Hash] A hash with :avg and :sd keys, values in minutes rounded to 1 decimal place.
+      def format_avg
+        time_stats.totals.slice(:avg, :sd).transform_values { |val| (val / 60.0).round(1) }
+      end
 
-        explanations << explanation.white
+      # Formats the total duration in hours.
+      # @return [Float] Total duration in hours rounded to 1 decimal place.
+      def format_total_hours
+        (total / 3600.0).round(1)
       end
 
-      # --- Overall Summary ---
-      if time_stats.sorted_duration_by_tag.any?
-        sorted_categories = time_stats.sorted_duration_by_tag.map do |tag, duration|
-          [tag, (duration.to_f / total * 100).round(1)]
-        end.sort_by { |_, percentage| -percentage }
-
-        major_categories = sorted_categories.select { |_, percentage| percentage > 10 }
-        if major_categories.size > 1
-          total_percentage = major_categories.sum { |_, percentage| percentage }
-          category_names = major_categories.map { |c, _| "'#{c.capitalize}'" }.join(' and ')
-          explanations << "\nTogether, #{category_names} dominate the time spent, accounting for nearly #{"#{total_percentage.round}%".bold} of the total.".white
+      # Calculates metrics for a specific tag.
+      # @param tag [String] The tag name.
+      # @param duration [Numeric] The duration for the tag.
+      # @return [Hash] A hash of metrics for the tag.
+      def tag_metrics(tag, duration)
+        stats = time_stats
+        value = duration.to_f / total
+        avg_sec = stats.average_by_tag[tag]
+        sd_sec = stats.standard_deviation_by_tag[tag]
+
+        {
+          tag: tag, duration: duration, percentage: (value * 100).round(1),
+          avg_minutes: (avg_sec / 60.0).round(1), sd_minutes: (sd_sec / 60.0).round(1),
+          avg_seconds: avg_sec, sd_seconds: sd_sec, value: value
+        }
+      end
+
+      def category_breakdown
+        time_stats.sorted_duration_by_tag.each_with_object(['Category Breakdown'.bold]) do |(tag, duration), parts|
+          parts << build_category_explanation(tag, duration).white
         end
       end
-      puts explanations.join("\n")
-    end
 
-    # Prints the summary information including total duration, average duration, and standard deviation.
-    #
-    # @param time_stats [Object] An object containing the time statistics, including totals.
-    # @param total [Numeric] The total duration of all tags combined.
-    # @return [void] This method outputs the summary information to the standard output.
-    def print_summary(time_stats, total)
-      avg = (time_stats.totals[:avg] / 60.0).round(1)
-      sd = (time_stats.totals[:sd] / 60.0).round(1)
-      summary = "#{' ' * TAG_SIZE} #{'Summary'.underline}: "
-      summary += "[T: #{(total / 3600.0).round(1)}h, AVG: #{avg}min SD: #{sd}min]".white
-      puts summary
-    end
+      def build_category_explanation(tag, duration)
+        metrics = tag_metrics(tag, duration)
+        [
+          "#{tag.capitalize.to_s.bold}:",
+          " This category consumed #{"#{metrics[:percentage]}%".bold} of the total tracked time.",
+          build_duration_part(duration), build_average_part(metrics),
+          sd_variation_message(metrics)
+        ].join
+      end
+
+      def sd_variation_message(metrics)
+        sd_min = metrics[:sd_minutes]
+        avg_hour = metrics[:avg_minutes] / 60.0
+        return high_sd_message(sd_min) if sd_min > avg_hour * 0.5
+        return moderate_sd_message(sd_min) if sd_min > avg_hour * 0.2
 
-    # Prints the detailed information for each tag.
-    #
-    # @param time_stats [Object] An object containing the time statistics, including sorted durations by tag.
-    # @param total [Numeric] The total duration of all tags combined.
-    # @param colors [Object] An object containing color formatting methods.
-    # @return [void] This method outputs the detailed tag information to the standard output.
-    def print_tags_info(time_stats, total, colors)
-      time_stats.sorted_duration_by_tag.each do |tag, duration|
-        value, bar_length = calculate_value_and_bar_length(duration, total)
-        horizontal_bar = generate_horizontal_bar(bar_length, colors[tag])
-        formatted_tag = tag[0...TAG_SIZE].rjust(TAG_SIZE)
-        stats = generate_stats(tag, time_stats)
-
-        puts "#{formatted_tag}: #{value.to_s.rjust(5)}%  #{horizontal_bar} [#{stats}]"
+        low_sd_message(sd_min)
       end
-    end
 
-    # Generates a horizontal bar for display based on the bar length and color index.
-    #
-    # @param bar_length [Numeric] The length of the bar to generate.
-    # @param color_index [Numeric] The color index to use for the bar.
-    # @return [String] The generated horizontal bar string.
-    def generate_horizontal_bar(bar_length, color_index)
-      (BLOCK_CHAR * bar_length).to_s.color(color_index + 1)
+      def build_sorted_categories
+        time_stats.sorted_duration_by_tag.map do |tag, duration|
+          [tag, tag_metrics(tag, duration)[:percentage]]
+        end.sort_by(&:last).reverse
+      end
+
+      def overall_summary
+        return [] unless time_stats.sorted_duration_by_tag.any?
+
+        major_categories = build_sorted_categories.select { |_, pct| pct > 10 }
+        return [] if major_categories.size <= 1
+
+        build_major_summary(major_categories)
+      end
+
+      def print_summary
+        f_avg = format_avg
+        summary = "#{' ' * TAG_SIZE} #{'Summary'.underline}: "
+        summary += "[T: #{format_total_hours}, AVG: #{f_avg[:avg]}min SD: #{f_avg[:sd]}min]".white
+        puts summary
+      end
+
+      def print_explanation
+        parts = []
+        parts << introduction(total)
+        parts << category_breakdown
+        parts << overall_summary
+        puts parts.flatten.join("\n")
+      end
+
+      def print_tags_info
+        stats = time_stats
+        stats.sorted_duration_by_tag.each do |tag, duration|
+          value, bar_length = calculate_value_and_bar_length(duration, total)
+          horizontal_bar = generate_horizontal_bar(bar_length, colors[tag])
+          formatted_tag = tag[0...TAG_SIZE].rjust(TAG_SIZE)
+          tag_stats = generate_stats(tag, stats)
+
+          puts "#{formatted_tag}: #{value.to_s.rjust(5)}%  #{horizontal_bar} [#{tag_stats}]"
+        end
+      end
+
+      def render
+        print_summary
+        print_tags_info
+      end
     end
 
-    # Generates the statistics string for a given tag.
-    #
-    # @param tag [String] The tag for which to generate the statistics.
-    # @param time_stats [Object] An object containing time statistics for the tags.
-    # @return [String] The generated statistics string.
-    def generate_stats(tag, time_stats)
-      total_hours = (time_stats.total_duration_by_tag[tag] / 3600.0).round(1)
-      avg_minutes = (time_stats.average_by_tag[tag] / 60.0).round(1)
-      sd_minutes = (time_stats.standard_deviation_by_tag[tag] / 60).round(1)
-      "T: #{total_hours}h, AVG: #{avg_minutes}min SD: #{sd_minutes}min".gray
+    include TagDistributionFormatting
+
+    def tag_distribution(colors)
+      time_stats = TimeStatistics.new(@items)
+      total = time_stats.total_duration
+
+      return unless total.positive?
+
+      ctx = Context.new(time_stats, total, colors)
+      ctx.render
+      print_footer
     end
 
-    # Calculates the percentage value and bar length for a given duration and total duration.
-    #
-    # @param duration [Numeric] The duration for the current tag.
-    # @param total [Numeric] The total duration.
-    # @return [Array<(Float, Integer)>] An array containing the calculated value and bar length.
-    #
-    # @example
-    #   calculate_value_and_bar_length(50, 100, 2) #=> [50.0, 25]
-    def calculate_value_and_bar_length(duration, total)
-      value = duration.to_f / total
-      percentage_value = (value * 100).round(1)
-      bar_length = (value * MAX_BAR_LENGTH).round
-      [percentage_value, bar_length]
+    def print_footer
+      puts '-' * 45
+      puts 'T:'.rjust(4).red + 'The total duration'.gray
+      puts 'AVG:'.rjust(4).red + 'The average duration'.gray
+      puts 'SD:'.rjust(4).red + 'The standard deviation of the durations'.gray
     end
   end
 end

data/lib/timet/time_helper.rb

@@ -278,9 +278,24 @@ module Timet
     def self.update_time_field(item, field, new_time)
       field_index = Timet::Application::FIELD_INDEX[field]
       timestamp = item[field_index]
-      edit_time = Time.at(timestamp || item[1]).to_s.split
-      edit_time[1] = new_time
-      DateTime.strptime(edit_time.join(' '), '%Y-%m-%d %H:%M:%S %z').to_time
+      base_time = Time.at(timestamp || item[1])
+
+      # Extract hours, minutes, and seconds from the new_time string
+      # Supports format "HH:MM:SS" or "HH:MM"
+      parts = new_time.split(':').map(&:to_i)
+      hours = parts[0]
+      minutes = parts[1]
+      seconds = parts[2] || 0
+
+      Time.new(
+        base_time.year,
+        base_time.month,
+        base_time.day,
+        hours,
+        minutes,
+        seconds,
+        base_time.utc_offset
+      )
     end
   end
 end

data/lib/timet/time_report.rb

@@ -3,7 +3,6 @@
 require 'date'
 require 'csv'
 require 'icalendar'
-require_relative 'time_report_helper'
 require_relative 'table'
 require_relative 'time_block_chart'
 require_relative 'tag_distribution'
@@ -13,7 +12,6 @@ module Timet
   # entries. It allows filtering the report by time periods and displays
   # a formatted table with the relevant information.
   class TimeReport
-    include TimeReportHelper
     include TagDistribution
 
     # Provides access to the database instance.
@@ -103,7 +101,10 @@ module Timet
     def print_tag_explanation_report
       time_stats = TimeStatistics.new(@items)
       total = time_stats.total_duration
-      print_explanation(time_stats, total) if total.positive?
+      return unless total.positive?
+
+      ctx = TagDistribution::Context.new(time_stats, total, nil)
+      ctx.print_explanation
     end
 
     # Displays a single row of the report.
@@ -133,6 +134,19 @@ module Timet
       @table.total
     end
 
+    def export_csv
+      file_name = "#{csv_filename}.csv"
+      write_csv(file_name)
+      puts "The #{file_name} has been exported."
+    end
+
+    def export_icalendar
+      file_name = "#{ics_filename}.ics"
+      cal = Timet::Utils.add_events(items)
+      File.write(file_name, cal.to_ical)
+      puts "The #{file_name} has been generated."
+    end
+
     private
 
     # Writes the items to a CSV file.

data/lib/timet/utils.rb

@@ -23,12 +23,12 @@ module Timet
       end
     end
 
-    # Converts a timestamp to a DateTime object.
+    # Converts a timestamp to a Time object.
     #
     # @param timestamp [Integer] the timestamp to convert
-    # @return [DateTime] the converted DateTime object
-    def self.convert_to_datetime(timestamp)
-      Time.at(timestamp).to_datetime
+    # @return [Time] the converted Time object
+    def self.convert_to_time(timestamp)
+      Time.at(timestamp)
     end
 
     # Provides predefined date ranges for filtering.
@@ -82,8 +82,8 @@ module Timet
     #
     # @note The method validates the date format for single dates and date ranges.
     def self.valid_date_format?(date_string)
-      date_format_single = /^\d{4}-\d{2}-\d{2}$/
-      date_format_range = /^\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}$/
+      date_format_single = /\A\d{4}-\d{2}-\d{2}\z/
+      date_format_range = /\A\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}\z/
 
       date_string.match?(date_format_single) || date_string.match?(date_format_range)
     end
@@ -93,8 +93,8 @@ module Timet
     # @param event [Icalendar::Event] the event object
     # @param item [Array] the item containing event details
     def self.assign_event_attributes(event, item)
-      dtstart = convert_to_datetime(item[1])
-      dtend = convert_to_datetime(item[2] || TimeHelper.current_timestamp)
+      dtstart = convert_to_time(item[1])
+      dtend = convert_to_time(item[2] || TimeHelper.current_timestamp)
 
       event.dtstart     = dtstart
       event.dtend       = dtend