timet 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f05df826f56c4161b878136fed6db433c86f717d1853dadc5b0255f98c5197e
-  data.tar.gz: 44699896bbfcc7b49409f4cb2bece028b4719ef9b1e97f7d83221ea1073e863f
+  metadata.gz: a3f1c37d739d4c6712cf21af39357a45ded45b8a63d8d7e9932ac859fe72b000
+  data.tar.gz: 20bf38e7554d3eb1326d1d7e2ae1095792c9b20a473d383f9f123e2ac0bbd2b2
 SHA512:
-  metadata.gz: 4af0f240762026b43a3e4c9f3833d81e51729c0ea6916537be9a9893e40d602e7f7fab49d2d552a6ee736f3efd3e8c7ea6f8ad2ff01f2306c97a0e6568b354ef
-  data.tar.gz: d368ea5f22cabd607a30056cbca07b4bc80501775a1bea9094d7c842a8277f3d2656fe334a6a038b2671475b9278c00ea7eb9adec15190e1f35e5f1dec44f142
+  metadata.gz: 92892c05063d444a713eaafec9eb63ff970a4926364b594dd31b61f229e9b415d3a171da61ffaa96660512708076423348ece7f120c0e21e075aa777e8e5b1b4
+  data.tar.gz: 3e1799d361eb28b500ce81740eb9ee1f16d55048e9425203aa6482265a9bc1d891e6d6897c626b454b2a18854523b99ed4acb0edf3a63e0dc043f16d1ebf4b04

data/CHANGELOG.md

@@ -1,13 +1,73 @@
 ## [Unreleased]
 
+## [1.2.0] - 2024-10-11
+
+**Improvements:**
+
+- Enhanced the README to provide more detailed and user-friendly information about the tool.
+- Added a visually appealing title and logo to make the README more engaging.
+- Organized key features into bullet points for better readability.
+- Provided clear and concise installation instructions.
+- Made the command reference more user-friendly by adding a table of contents.
+- Added more details about data storage and development guidelines.
+- Encouraged contributions and provided guidelines for contributing.
+- Made the support section more prominent.
+- Ensured the license and code of conduct are clearly stated.
+- Updated the `timet` gem version to 1.2.0 in `Gemfile.lock`.
+- Refactored the `play_sound_and_notify` condition to use the `positive?` method for better readability.
+- Enhanced table header formatting with a blinking effect for better user interaction.
+- Added new methods for tag distribution and time block chart visualization:
+  - `format_tag_distribution`: Displays tag distribution with progress bars.
+  - `print_time_block_chart`: Prints the entire time block chart.
+  - `print_header`: Prints the header of the time block chart.
+  - `print_blocks`: Prints the block characters for each hour.
+  - `get_block_char`: Determines the block character based on value.
+- Added `count_seconds_per_hour_block` method to count seconds per hour block.
+- Added `aggregate_hash_values` method to aggregate hash values.
+- Integrated new methods into `time_report` to enhance time tracking visualization.
+- Updated the version number in `lib/timet/version.rb` to 1.2.0.
+
+### Additional Considerations:
+
+- The enhancements made in this pull request aim to improve the user experience and provide more powerful visualization and reporting capabilities for time tracking.
+- Reviewers are encouraged to test the new visualization methods and provide feedback on their effectiveness and usability.
+- The README updates should make it easier for new users to understand and use the `timet` tool.
+
+## [1.0.0] - 2024-10-07
+
+**Improvements:**
+
+- Added a `pomodoro` option to the `start` command to specify Pomodoro time in minutes.
+- Updated the `start` method to accept an optional `pomodoro` parameter and call `play_sound_and_notify` if Pomodoro time is provided.
+- Improved the `stop` method to accept an optional `display` parameter and conditionally call `summary`.
+- Added `play_sound_and_notify` method to `application_helper.rb` for playing a sound and sending a notification after a specified time.
+- Updated RSpec tests to reflect the new `pomodoro` parameter and `display` parameter in the `start` and `stop` methods, respectively.
+- Converted Pomodoro time from minutes to seconds before passing it to `play_sound_and_notify`.
+
+### Bug fixes:
+
+- Ensured Pomodoro time is a positive integer before invoking `play_sound_and_notify`.
+
+#### Tasks:
+
+- Update README.md to document the new Pomodoro feature.
+
+### Additional Considerations:
+
+- The `pomodoro` option is designed to be flexible, allowing users to specify any duration in minutes for their Pomodoro sessions. This flexibility caters to users who may prefer different interval lengths based on their work habits and preferences.
+- The `play_sound_and_notify` method is a new addition to the `application_helper.rb` file, providing a mechanism for notifying users when their Pomodoro session ends. This feature includes both a sound notification and a system notification to ensure users are aware of the end of their work interval.
+- The `stop` method has been improved to accept an optional `display` parameter, which allows users to conditionally call the `summary` method. This enhancement provides more control over when the summary of the time tracking session is displayed.
+- The RSpec tests have been updated to reflect the new parameters and functionality introduced in this pull request, ensuring that the code remains robust and reliable.
+
 ## [0.9.2] - 2024-10-06
 
 **Improvements:**
+
 - Improved the description of the 'start' command to clarify the usage of optional notes.
 
 **Bug fixes:**
-- Modified the 'display_item' method to handle cases where 'updated_item' is nil, ensuring that the original 'item' is displayed instead.
 
+- Modified the 'display_item' method to handle cases where 'updated_item' is nil, ensuring that the original 'item' is displayed instead.
 
 ## [0.9.1] - 2024-10-04
 

data/README.md

@@ -5,18 +5,42 @@
 
 # Timet
 
+![Timet](timet.webp)
+
 Timet refers to a command-line tool designed to track your activities by recording the time spent on each task, allowing you to monitor your work hours and productivity directly from your terminal without needing a graphical interface; essentially, it's a way to log your time spent on different projects or tasks using simple text commands
 
-Timet utilizes SQLite to store your time tracking data. This means your data is stored locally and securely, with no need for external databases or cloud storage. This makes Timet lightweight, fast, and perfect for users who value privacy and control over their data.
+**Key Features:**
 
-While a YAML file might seem like a simple option for storing time tracking data, Timet leverages SQLite for several key advantages:
+- **Local Data Storage:** Timet utilizes SQLite to store your time tracking data locally, ensuring privacy and security.
+- **Lightweight and Fast:** Its efficient design and local data storage make Timet a speedy and responsive tool.
+- **Structured Data:** SQLite ensures your data is organized and easily accessible.
+- **Scalability:** Timet can handle growing time tracking needs.
+- **Data Integrity:** SQLite maintains the accuracy and consistency of your data.
+- **Querying and Reporting:** Generate detailed reports for specific periods.
+- **CSV Export:** Easily export your time tracking data to CSV format for further analysis or sharing.
+- **Pomodoro Integration:** The pomodoro option in the start command enhances time tracking by integrating the Pomodoro Technique.
+- **Block Time Plot:** Visualizes the distribution of tracked time across a 24-hour period, with bars in each column representing the amount of time tracked during that specific hour.
+- **Tag Distribution Plot:** Illustrates the proportion of total tracked time allocated to each tag, showing the relative contribution of each tag to the overall time tracked.
 
-- Structured Data
-- Scalability
-- Data Integrity
-- Querying and Reporting
+Example:
 
-In addition, if possible, export your time tracking data to CSV for analysis and sharing.
+```bash
+Tracked time report [today]:
++-------+------------+--------+----------+----------+----------+--------------------------+
+| Id    | Date       | Tag    | Start    | End      | Duration | Notes                    |
++-------+------------+--------+----------+----------+----------+--------------------------+
+|    20 | 2024-10-10 | Tag8   | 19:26:58 | 20:26:58 | 01:00:00 | Notes 2                  |
+|    19 |            | Tag3   | 07:52:26 | 08:52:26 | 01:00:00 | Notes 7                  |
++-------+------------+--------+----------+----------+----------+--------------------------+
+|                                           Total:  | 02:00:00 |                          |
++-------+------------+--------+----------+----------+----------+--------------------------+
+
+⏳ ↦ ┏ 00  01  02  03  04  05  06  07  08  09  10  11  12  13  14  15  16  17  18  19  20  21  22  23  
+     ┗                             ▂▂  ▇▇                                          ▅▅  ▄▄              
+
+    Tag8:    50.0%  ▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅
+    Tag3:    50.0%  ▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅
+```
 
 ## Requirements
 
@@ -39,14 +63,20 @@ gem install timet
 
 ## Usage
 
-- timet start [tag] --notes="" --pomodoro=[minutes]**: Starts tracking time for a task labeled with the provided [tag],  notes and "pomodoro time" in minutes (optional). Example:
+### Command Aliases
+
+- `timet`: The primary command for interacting with the Timet application.
+- `tt`: An alias for the `timet` command, providing a shorter alternative.
+
+---
+- **timet start [tag] --notes="" --pomodoro=[minutes]**: Starts tracking time for a task labeled with the provided [tag],  notes and "pomodoro time" in minutes (optional). Example:
 
   ```bash
   timet start task1 --notes="Meeting with client" --pomodoro=25
 
   or
 
-  timet start task1 "Meeting with client" 25
+  tt start task1 "Meeting with client" 25
   ```
 
   ```
@@ -110,7 +140,7 @@ gem install timet
 - **Interactive Mode:**
 
   ```bash
-  timet e 1
+  timet edit 1
   ```
 
   ```
@@ -201,9 +231,14 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/frankv
 
 Many people have contacted me asking how to contribute. Any contribution, from a virtual coffee to a kind word, is greatly appreciated and helps me continue my work. Please only donate if you're able, as there are no refunds. Your support is entirely voluntary, and I thank you for your consideration.
 
+**Bitcoin Address:**
+```sh
+bc1qkg9me2jsuhpzu2hp9kkpxagwtf9ewnyfl4kszl 
+```
+
 ![Buy me a coffee!](btc.png)
 
-bc1qkg9me2jsuhpzu2hp9kkpxagwtf9ewnyfl4kszl
+---
 
 ## License
 

data/bin/tt

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/timet'
+
+Timet::Application.start(ARGV)

data/lib/timet/application.rb

@@ -66,7 +66,7 @@ module Timet
 
       if VALID_STATUSES_FOR_INSERTION.include?(@db.last_item_status)
         @db.insert_item(start_time, tag, notes)
-        play_sound_and_notify(pomodoro * 60, tag) if pomodoro > 0
+        play_sound_and_notify(pomodoro * 60, tag) if pomodoro.positive?
       end
       summary
     end
@@ -245,6 +245,18 @@ module Timet
       true
     end
 
+    #   Displays the current version of the Timet gem.
+    #
+    #   @example
+    #     $ timet version
+    #     1.0.0
+    #
+    #   @return [void] This method does not return a value; it prints the version to the standard output.
+    desc 'version', 'version'
+    def version
+      puts Timet::VERSION
+    end
+
     private
 
     # Deletes a tracking item from the database by its ID and prints a confirmation message.

data/lib/timet/formatter.rb

@@ -14,7 +14,7 @@ module Timet
     # @note The method constructs a string representing the table header and prints it.
     def format_table_header
       header = <<~TABLE
-        Tracked time report \u001b[31m[#{@filter}]\033[0m:
+        Tracked time report \e[5m\u001b[31m[#{@filter}]\033[0m:
         #{format_table_separator}
         \033[32m| Id    | Date       | Tag    | Start    | End      | Duration | Notes                    |\033[0m
         #{format_table_separator}
@@ -64,5 +64,120 @@ module Timet
       notes = "#{notes.slice(0, 20)}..." if notes.length > 20
       notes.ljust(23)
     end
+
+    # @!method format_tag_distribution(duration_by_tag)
+    #   Formats and displays the tag distribution.
+    #
+    #   @example
+    #     duration_by_tag = { "timet" => 3600, "nextjs" => 1800 }
+    #     Formatter.format_tag_distribution(duration_by_tag)
+    #     # Output:
+    #     #    timet:   66.67%  \u001b[38;5;42m====================\u001b[0m
+    #     #   nextjs:   33.33%  \u001b[38;5;42m==========\u001b[0m
+    #
+    #   @param duration_by_tag [Hash<String, Integer>] A hash where keys are tags and values are durations in seconds.
+    #   @return [void] This method outputs the formatted tag distribution to the console.
+    def format_tag_distribution(duration_by_tag)
+      block = '▅'
+      total = duration_by_tag.values.sum
+      return unless total.positive?
+
+      factor = duration_by_tag.size < 3 ? 2 : 1
+      sorted_duration_by_tag = duration_by_tag.sort_by { |_, duration| -duration }
+
+      sorted_duration_by_tag.each do |tag, duration|
+        value = (duration.to_f / total * 100).round(2)
+        puts "#{tag.rjust(8)}: #{value.to_s.rjust(7)}%  \u001b[38;5;#{rand(256)}m#{block * (value / factor).to_i}\u001b[0m"
+      end
+    end
+
+    # Prints the entire time block chart.
+    #
+    # This method orchestrates the printing of the entire time block chart by calling
+    # the `print_header` and `print_blocks` methods. It also prints the separator line
+    # between the header and the blocks, and adds a double newline at the end for
+    # separation.
+    #
+    # @param time_block [Hash] A hash where the keys are formatted hour strings
+    #                          (e.g., "00", "01") and the values are the corresponding
+    #                          values to determine the block character.
+    # @example
+    #   time_block = { "00" => 100, "01" => 200, ..., "23" => 300 }
+    #   print_time_block_chart(time_block)
+    #   # Output:
+    #   # ⏳ ↦ ┏ 00  01  02  03  04  05  06  07  08  09  10  11  12  13  14  15  16  17  18  19  20  21  22  23
+    #   #      ┗ ▁ ▂ ▃ ▄ ▅ ▆ ▇ █ ▁ ▂ ▃ ▄ ▅ ▆ ▇ █ ▁ ▂ ▃ ▄ ▅ ▆ ▇ █
+    #   #
+    #   # (followed by two newlines)
+    #
+    def print_time_block_chart(time_block)
+      print_header
+      print '     ┗ '
+      print_blocks(time_block)
+    end
+
+    # Prints the header of the time block chart.
+    #
+    # This method outputs the header line of the chart, which includes the hours
+    # from 00 to 23, formatted and aligned for readability.
+    #
+    # @example
+    #   print_header
+    #   # Output:
+    #   # ⏳ ↦ ┏ 00  01  02  03  04  05  06  07  08  09  10  11  12  13  14  15  16  17  18  19  20  21  22  23
+    #
+    def print_header
+      puts
+      print '⏳ ↦ ┏ '
+      (0..23).each { |hour| print format('%02d', hour).ljust(4) }
+      puts
+    end
+
+    # Prints the block characters for each hour in the time block chart.
+    #
+    # This method iterates over each hour from 0 to 23, retrieves the corresponding
+    # block character using the `get_block_char` method, and prints it aligned for
+    # readability. It also adds a double newline at the end for separation.
+    #
+    # @param time_block [Hash] A hash where the keys are formatted hour strings
+    #                          (e.g., "00", "01") and the values are the corresponding
+    #                          values to determine the block character.
+    # @example
+    #   time_block = { "00" => 100, "01" => 200, ..., "23" => 300 }
+    #   print_blocks(time_block)
+    #   # Output:
+    #   # ▁ ▂ ▃ ▄ ▅ ▆ ▇ █ ▁ ▂ ▃ ▄ ▅ ▆ ▇ █ ▁ ▂ ▃ ▄ ▅ ▆ ▇ █
+    #   #
+    #   # (followed by two newlines)
+    #
+    def print_blocks(time_block)
+      return unless time_block
+
+      (0..23).each do |hour|
+        block_char = get_block_char(time_block[format('%02d', hour)])
+        print (block_char * 2).ljust(4)
+      end
+      puts "\n\n"
+    end
+
+    # Determines the block character based on the value.
+    #
+    # @param value [Integer] The value to determine the block character for.
+    # @return [String] The block character corresponding to the value.
+    def get_block_char(value)
+      range_to_char = {
+        0..120 => ' ',
+        121..450 => '▁',
+        451..900 => '▂',
+        901..1350 => '▃',
+        1351..1800 => '▄',
+        1801..2250 => '▅',
+        2251..2700 => '▆',
+        2701..3150 => '▇',
+        3151..3600 => '█'
+      }
+
+      range_to_char.find { |range, _| range.include?(value) }&.last || ' '
+    end
   end
 end

data/lib/timet/time_helper.rb

@@ -168,5 +168,71 @@ module Timet
     def self.current_timestamp
       Time.now.utc.to_i
     end
+
+    # Counts the number of seconds for each hour block between the given start and end times.
+    #
+    # This method calculates the number of seconds each event spans within each hour block
+    # and aggregates the results in a hash where the keys are the hour blocks (in 'HH' format)
+    # and the values are the total number of seconds for each hour block.
+    #
+    # @param start_time [Integer] The start time in seconds since the Unix epoch.
+    # @param end_time [Integer] The end time in seconds since the Unix epoch. If not provided,
+    #                           the current time will be used.
+    # @return [Hash] A hash where the keys are the hour blocks (in 'HH' format) and the values
+    #                are the total number of seconds for each hour block.
+    # @example
+    #   start_time = 1728577349  # 8:30 AM
+    #   end_time = 1728579200    # 11:20 AM
+    #   result = count_seconds_per_hour_block(start_time, end_time)
+    #   # Output: {"08"=>1800, "09"=>1800, "10"=>3600, "11"=>1200}
+    #
+    def self.count_seconds_per_hour_block(start_time, end_time)
+      hour_blocks = Hash.new(0)
+
+      current_time = Time.at(start_time)
+      end_time = Time.at(end_time || current_timestamp)
+
+      while current_time < end_time
+        current_hour = current_time.hour
+        next_hour_boundary = Time.new(current_time.year, current_time.month, current_time.day, current_hour + 1)
+
+        block_end_time = [next_hour_boundary, end_time].min
+        seconds_in_block = (block_end_time - current_time).to_i
+
+        hour_block = current_time.strftime('%H')
+        hour_blocks[hour_block] += seconds_in_block
+
+        current_time = block_end_time
+      end
+
+      hour_blocks
+    end
+
+    # Aggregates the values of the same keys from an array of hashes.
+    #
+    # This method takes an array of hashes, reverses it, and then aggregates the values
+    # for the same keys into a single hash. If a key appears in multiple hashes, its
+    # values are summed.
+    #
+    # @param time_block [Array<Hash>] An array of hashes where each hash contains key-value pairs.
+    # @return [Hash] A hash where the keys are the aggregated keys from the input hashes
+    #                and the values are the summed values for each key.
+    # @example
+    #   time_block = [
+    #     {"01": 10},
+    #     {"01": 30},
+    #     {"02": 50}
+    #   ]
+    #   result = aggregate_hash_values(time_block)
+    #   # Output: {"01"=>40, "02"=>50}
+    #
+    def self.aggregate_hash_values(time_block)
+      time_block.reverse.each_with_object({}) do |hash, acc|
+        hash.each do |key, value|
+          acc[key] ||= 0
+          acc[key] += value
+        end
+      end
+    end
   end
 end

data/lib/timet/time_report.rb

@@ -51,12 +51,23 @@ module Timet
       return puts 'No tracked time found for the specified filter.' if items.empty?
 
       format_table_header
+      duration_by_tag = Hash.new(0)
+      time_block = []
       items.each_with_index do |item, idx|
         date = TimeHelper.extract_date(items, idx)
         display_time_entry(item, date)
+        time_block << TimeHelper.count_seconds_per_hour_block(item[1], item[2])
+        duration_by_tag[item[3]] += TimeHelper.calculate_duration(item[1], item[2])
       end
       puts format_table_separator
       total
+
+      if Time.now.to_i - items.map { |x| x[1] }.min < 86_400
+        time_block_reverse = TimeHelper.aggregate_hash_values(time_block)
+        print_time_block_chart(time_block_reverse)
+      end
+
+      format_tag_distribution(duration_by_tag)
     end
 
     # Displays a single row of the report.

data/lib/timet/version.rb

@@ -6,6 +6,6 @@ module Timet
   # @return [String] The version number in the format 'major.minor.patch'.
   #
   # @example Get the version of the Timet application
-  #   Timet::VERSION # => '1.0.0'
-  VERSION = '1.0.0'
+  #   Timet::VERSION # => '1.2.0'
+  VERSION = '1.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: timet
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Frank Vielma
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-07 00:00:00.000000000 Z
+date: 2024-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -63,6 +63,7 @@ email:
 - frankvielma@gmail.com
 executables:
 - timet
+- tt
 extensions: []
 extra_rdoc_files: []
 files:
@@ -75,6 +76,7 @@ files:
 - README.md
 - Rakefile
 - bin/timet
+- bin/tt
 - btc.png
 - lib/timet.rb
 - lib/timet/application.rb
@@ -87,6 +89,7 @@ files:
 - lib/timet/validation_edit_helper.rb
 - lib/timet/version.rb
 - sig/timet.rbs
+- timet.webp
 homepage: https://frankvielma.github.io/posts/timet-a-powerful-command-line-tool-for-tracking-your-time/
 licenses:
 - MIT