timet 1.1.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cf486dcc89da9e06f1a77b36d3183a1f8c55a11ce51e79a761cbb84280af9ba
-  data.tar.gz: fe4cbc8baf03c019cfbb8b31514a9e5fd99ba1320c8cf27945dacf6fd1033784
+  metadata.gz: db3c3e635b08a071bc271be5788a4b689f0a28203dea81c2dc73a78c312b089e
+  data.tar.gz: 2c5c831731c0ec619064653b8239381a53e5c973f92f347e98a74de8c07547e0
 SHA512:
-  metadata.gz: 0d2ddea11803e4d0225858ed1edb2b3143ad7579959f057a9025ff9db82acccaf3de1aed4018f99c856ed97c896d3d775a2d14224251e9d325b9aceef223db11
-  data.tar.gz: d6b6b852de2aea0966aa0e108ee73a64c30bbdb88217ad8806ab66ce732de32641f71692c3eaf4fd1fc9421c4722d6300ae86ce8051f5c3ec9d34f6d4631ad96
+  metadata.gz: 0b98ea65edc254804e58c16ce0f200209ee57b9b3629fc182ec822c1b359380015bdaf281db64a9bd96acaa5ded45489f4464602ae90ab3e11916556e879e88a
+  data.tar.gz: fba083a2484a17a3af3efb5c0d2dcad4b08f463d162b6689c4a6445948d6f2bd517ef0b3efd794d0b0b05a818799798446a65902cf97ebe94519f884aa2c9927

data/CHANGELOG.md

@@ -1,5 +1,74 @@
 ## [Unreleased]
 
+## [1.2.1] - 2024-10-18
+
+**Improvements:**
+- Updated the time block chart formatting to use square brackets for better visual representation.
+- Refactored the `play_sound_and_notify` method to avoid redundant platform checks and introduced platform-specific session runners.
+- Improved readability and maintainability of the `format_tag_distribution` method by extracting logic into a new private method.
+- Updated the `rubocop` gem from `~> 1.65` to `~> 1.67`.
+
+### Bug fixes:
+- Fixed a `NoMethodError` caused by an undefined method `process_and_print_tags` in the `format_tag_distribution` method.
+- Fixed line length violations in several files to comply with `rubocop` rules.
+
+### Additional Considerations:
+- The changes in this pull request should be thoroughly tested to ensure that they do not introduce any regressions.
+- Future improvements could include further refactoring to extract more logic into separate methods or classes, depending on the complexity and requirements of the application.
+
+## [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.1.0] - 2024-10-09
+
+**Improvements:**
+
+- Added a new `version` command to display the current version of the Timet gem.
+- Introduced an alias `tt` for the `timet` command, providing a shorter alternative.
+- Updated the README to include the `tt` alias and provide examples for both `timet` and `tt` commands.
+- Updated the gem version to `1.1.0`.
+- Added the `tt` executable to the gemspec.
+- Updated the `rspec-mocks` dependency to version `3.13.2`.
+
+**Tasks:**
+
+- Update `Gemfile.lock` to reflect the new gem version and updated dependencies.
+- Add the `tt` executable script to the `bin` directory.
+- Update the `version` command in `lib/timet/application.rb` with Yardoc documentation.
+- Update the `VERSION` constant in `lib/timet/version.rb` to `1.1.0`.
+- Update the `timet.gemspec` to include the `tt` executable.
+- Update the README to reflect the new `tt` alias and provide examples for both `timet` and `tt` commands.
+
 ## [1.0.0] - 2024-10-07
 
 **Improvements:**

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
 
@@ -207,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/lib/timet/application.rb

@@ -45,10 +45,13 @@ module Timet
     # trigger a sound and notification after the specified time has elapsed.
     #
     # @param tag [String] The tag associated with the tracking session. This is a required parameter.
-    # @param notes [String, nil] Optional notes to be associated with the tracking session. If not provided, it defaults to the value in `options[:notes]`.
-    # @param pomodoro [Numeric, nil] Optional Pomodoro time in minutes. If not provided, it defaults to the value in `options[:pomodoro]`.
+    # @param notes [String, nil] Optional notes to be associated with the tracking session. If not provided, it
+    # defaults to the value in `options[:notes]`.
+    # @param pomodoro [Numeric, nil] Optional Pomodoro time in minutes. If not provided, it defaults to the value in
+    # `options[:pomodoro]`.
     #
-    # @return [void] This method does not return a value; it performs side effects such as inserting a tracking item, playing a sound, sending a notification, and generating a summary.
+    # @return [void] This method does not return a value; it performs side effects such as inserting a tracking item,
+    # playing a sound, sending a notification, and generating a summary.
     #
     # @example Start a tracking session with a tag and notes
     #   start('work', 'Starting work on project X', 25)
@@ -66,7 +69,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
@@ -74,14 +77,17 @@ module Timet
     desc 'stop', 'stop time tracking'
     # Stops the current tracking session if there is one in progress.
     #
-    # @return [void] This method does not return a value; it performs side effects such as updating the tracking item and generating a summary.
+    # @return [void] This method does not return a value; it performs side effects such as updating the tracking item
+    # and generating a summary.
     #
     # @example Stop the current tracking session
     #   stop
     #
     # @note The method checks if the last tracking item is in progress by calling `@db.last_item_status`.
-    # @note If the last item is in progress, it fetches the last item's ID using `@db.fetch_last_id` and updates it with the current timestamp.
-    # @note The method then fetches the last item using `@db.last_item` and generates a summary if the result is not nil.
+    # @note If the last item is in progress, it fetches the last item's ID using `@db.fetch_last_id` and updates it
+    # with the current timestamp.
+    # @note The method then fetches the last item using `@db.last_item` and generates a summary if the result
+    # is not nil.
     def stop(display = nil)
       return unless @db.last_item_status == :in_progress
 
@@ -94,14 +100,16 @@ module Timet
     desc 'resume (r)', 'resume last task'
     # Resumes the last tracking session if it was completed.
     #
-    # @return [void] This method does not return a value; it performs side effects such as resuming a tracking session or providing feedback.
+    # @return [void] This method does not return a value; it performs side effects such as resuming a tracking session
+    # or providing feedback.
     #
     # @example Resume the last tracking session
     #   resume
     #
     # @note The method checks the status of the last tracking item using `@db.last_item_status`.
     # @note If the last item is in progress, it prints a message indicating that a task is currently being tracked.
-    # @note If the last item is complete, it fetches the last item using `@db.last_item`, retrieves the tag and notes, and calls the `start` method to resume the tracking session.
+    # @note If the last item is complete, it fetches the last item using `@db.last_item`, retrieves the tag and notes,
+    # and calls the `start` method to resume the tracking session.
     def resume
       status = @db.last_item_status
 
@@ -121,12 +129,15 @@ module Timet
     desc 'summary (su) [filter] [tag] --csv=csv_filename',
          '  [filter] => [today (t), yesterday (y), week (w), month (m), [start_date]..[end_date]]  [tag]'
     option :csv, type: :string, desc: 'Export to CSV file'
-    # Generates a summary of tracking items based on the provided filter and tag, and optionally exports the summary to a CSV file.
+    # Generates a summary of tracking items based on the provided filter and tag, and optionally exports the summary
+    # to a CSV file.
     #
-    # @param filter [String, nil] The filter to apply when generating the summary. Possible values include 'today', 'yesterday', 'week', 'month', or a date range in the format '[start_date]..[end_date]'.
+    # @param filter [String, nil] The filter to apply when generating the summary. Possible values include 'today',
+    # 'yesterday', 'week', 'month', or a date range in the format '[start_date]..[end_date]'.
     # @param tag [String, nil] The tag to filter the tracking items by.
     #
-    # @return [void] This method does not return a value; it performs side effects such as displaying the summary and exporting to CSV if specified.
+    # @return [void] This method does not return a value; it performs side effects such as displaying the summary and
+    # exporting to CSV if specified.
     #
     # @example Generate a summary for today
     #   summary('today')
@@ -139,7 +150,8 @@ module Timet
     #
     # @note The method initializes a `TimeReport` object with the database, filter, tag, and optional CSV filename.
     # @note The method calls `display` on the `TimeReport` object to show the summary.
-    # @note If a CSV filename is provided and there are items to export, the method calls `export_sheet` to export the summary to a CSV file.
+    # @note If a CSV filename is provided and there are items to export, the method calls `export_sheet` to export the
+    # summary to a CSV file.
     # @note If no items are found to export, it prints a message indicating that no items were found.
     def summary(filter = nil, tag = nil)
       csv_filename = options[:csv]&.split('.')&.first
@@ -156,13 +168,17 @@ module Timet
 
     desc 'edit (e) [id] [field] [value]',
          'edit a task, [field] (notes, tag, start or end) and [value] are optional parameters'
-    # Edits a specific tracking item by its ID, allowing the user to modify fields such as notes, tag, start time, or end time.
+    # Edits a specific tracking item by its ID, allowing the user to modify fields such as notes, tag, start time, or
+    # end time.
     #
     # @param id [Integer] The ID of the tracking item to be edited.
-    # @param field [String, nil] The field to be edited. Possible values include 'notes', 'tag', 'start', or 'end'. If not provided, the user will be prompted to select a field.
-    # @param new_value [String, nil] The new value to be set for the specified field. If not provided, the user will be prompted to enter a new value.
+    # @param field [String, nil] The field to be edited. Possible values include 'notes', 'tag', 'start', or 'end'.
+    # If not provided, the user will be prompted to select a field.
+    # @param new_value [String, nil] The new value to be set for the specified field. If not provided, the user will be
+    # prompted to enter a new value.
     #
-    # @return [void] This method does not return a value; it performs side effects such as updating the tracking item and displaying the updated item.
+    # @return [void] This method does not return a value; it performs side effects such as updating the tracking item
+    # and displaying the updated item.
     #
     # @example Edit the notes of a tracking item with ID 1
     #   edit(1, 'notes', 'Updated notes')
@@ -172,7 +188,8 @@ module Timet
     #
     # @note The method first attempts to find the tracking item by its ID using `@db.find_item(id)`.
     # @note If the item is found, it displays the current item details using `display_item(item)`.
-    # @note If the field or new value is not provided, the user is prompted to select a field to edit and enter a new value.
+    # @note If the field or new value is not provided, the user is prompted to select a field to edit and enter
+    # a new value.
     # @note The method then validates and updates the item using `validate_and_update(item, field, new_value)`.
     # @note Finally, it displays the updated item details using `display_item(updated_item)`.
     def edit(id, field = nil, new_value = nil)
@@ -194,15 +211,18 @@ module Timet
     #
     # @param id [Integer] The ID of the tracking item to be deleted.
     #
-    # @return [void] This method does not return a value; it performs side effects such as deleting the tracking item and displaying a confirmation message.
+    # @return [void] This method does not return a value; it performs side effects such as deleting the tracking item
+    # and displaying a confirmation message.
     #
     # @example Delete a tracking item with ID 1
     #   delete(1)
     #
     # @note The method first attempts to find the tracking item by its ID using `@db.find_item(id)`.
     # @note If the item is found, it displays the item details using `TimeReport.new(@db).show_row(item)`.
-    # @note The method then prompts the user for confirmation using `TTY::Prompt.new.yes?('Are you sure you want to delete this entry?')`.
-    # @note If the user confirms, the method deletes the item and prints a confirmation message using `delete_item_and_print_message(id, "Deleted #{id}")`.
+    # @note The method then prompts the user for confirmation using `TTY::Prompt.new.yes?('Are you sure you want
+    # to delete this entry?')`.
+    # @note If the user confirms, the method deletes the item and prints a confirmation message using
+    # `delete_item_and_print_message(id, "Deleted #{id}")`.
     def delete(id)
       item = @db.find_item(id)
       return puts "No tracked time found for id: #{id}" unless item
@@ -216,14 +236,16 @@ module Timet
     desc 'cancel (c)', 'cancel active time tracking'
     # Cancels the active time tracking session by deleting the last tracking item.
     #
-    # @return [void] This method does not return a value; it performs side effects such as deleting the active tracking item and displaying a confirmation message.
+    # @return [void] This method does not return a value; it performs side effects such as deleting the active tracking
+    # item and displaying a confirmation message.
     #
     # @example Cancel the active time tracking session
     #   cancel
     #
     # @note The method fetches the ID of the last tracking item using `@db.fetch_last_id`.
     # @note It checks if the last item is in progress by comparing `@db.last_item_status` with `:complete`.
-    # @note If the last item is in progress, it deletes the item and prints a confirmation message using `delete_item_and_print_message(id, "Canceled active time tracking #{id}")`.
+    # @note If the last item is in progress, it deletes the item and prints a confirmation message using
+    # `delete_item_and_print_message(id, "Canceled active time tracking #{id}")`.
     # @note If there is no active time tracking, it prints a message indicating that there is no active time tracking.
     def cancel
       id = @db.fetch_last_id
@@ -240,7 +262,8 @@ module Timet
     #   MyClass.exit_on_failure? # => true
     #
     # @note This method is typically used in command-line applications to control the behavior when a command fails.
-    # @note Returning `true` means that the application will exit immediately if a command fails, which is useful for ensuring that errors are handled gracefully.
+    # @note Returning `true` means that the application will exit immediately if a command fails, which is useful for
+    # ensuring that errors are handled gracefully.
     def self.exit_on_failure?
       true
     end
@@ -264,7 +287,8 @@ module Timet
     # @param id [Integer] The ID of the tracking item to be deleted.
     # @param message [String] The message to be printed after the item is deleted.
     #
-    # @return [void] This method does not return a value; it performs side effects such as deleting the tracking item and printing a message.
+    # @return [void] This method does not return a value; it performs side effects such as deleting the tracking item
+    # and printing a message.
     #
     # @example Delete a tracking item with ID 1 and print a confirmation message
     #   delete_item_and_print_message(1, 'Deleted item 1')

data/lib/timet/application_helper.rb

@@ -12,7 +12,8 @@ module Timet
     # @example Display the details of a tracking item
     #   display_item(item)
     #
-    # @note The method initializes a `TimeReport` object with the database and calls `show_row` to display the item details.
+    # @note The method initializes a `TimeReport` object with the database and calls `show_row` to display the
+    # item details.
     def display_item(item)
       TimeReport.new(@db).show_row(item)
     end
@@ -28,7 +29,8 @@ module Timet
     #   prompt_for_new_value(item, 'notes')
     #
     # @note The method retrieves the current value of the field using `field_value`.
-    # @note The method uses `TTY::Prompt.new` to prompt the user for a new value, displaying the current value in the prompt.
+    # @note The method uses `TTY::Prompt.new` to prompt the user for a new value, displaying the current value
+    # in the prompt.
     def prompt_for_new_value(item, field)
       current_value = field_value(item, field)
       prompt = TTY::Prompt.new(active_color: :green)
@@ -54,13 +56,15 @@ module Timet
     # @param item [Hash] The tracking item.
     # @param field [String] The field to retrieve the value for.
     #
-    # @return [String, Time] The value of the specified field. If the field is 'start' or 'end', it returns the value as a Time object.
+    # @return [String, Time] The value of the specified field. If the field is 'start' or 'end', it returns the value
+    # as a Time object.
     #
     # @example Retrieve the value of the 'notes' field
     #   field_value(item, 'notes')
     #
     # @note The method retrieves the index of the field from `Timet::Application::FIELD_INDEX`.
-    # @note If the field is 'start' or 'end', the method converts the value to a Time object using `TimeHelper.timestamp_to_time`.
+    # @note If the field is 'start' or 'end', the method converts the value to a Time object
+    # using `TimeHelper.timestamp_to_time`.
     def field_value(item, field)
       index = Timet::Application::FIELD_INDEX[field]
       value = item[index]
@@ -89,15 +93,38 @@ module Timet
     #
     # @return [void]
     def play_sound_and_notify(time, tag)
-      if RUBY_PLATFORM.downcase.include?('linux')
-        pid = spawn("sleep #{time} && tput bel && /home/frank/Software/frankvielma/gems/timet/bin/timet stop 0 && notify-send --icon=clock 'Pomodoro session complete! (tag: #{tag}) Time for a break.' &")
-        Process.wait(pid)
-      elsif RUBY_PLATFORM.downcase.include?('darwin')
-        pid = spawn("(sleep #{time} && afplay /System/Library/Sounds/Basso.aiff && osascript -e 'display notification \"Pomodoro session complete! Time for a break.\"') &")
-        Process.wait(pid)
+      platform = RUBY_PLATFORM.downcase
+      if platform.include?('linux')
+        run_linux_session(time, tag)
+      elsif platform.include?('darwin')
+        run_mac_session(time, tag)
       else
         puts 'Unsupported operating system'
       end
     end
+
+    # Runs a Pomodoro session on a Linux system.
+    #
+    # @param time [Integer] The duration of the Pomodoro session in seconds.
+    # @param tag [String] A tag or label for the session, used in the notification message.
+    # @return [void]
+    def run_linux_session(time, tag)
+      notification_command = "notify-send --icon=clock 'Pomodoro session complete! (tag: #{tag}) Time for a break.'"
+      command = "sleep #{time} && tput bel && tt stop 0 && #{notification_command} &"
+      pid = spawn(command)
+      Process.wait(pid)
+    end
+
+    # Runs a Pomodoro session on a macOS system.
+    #
+    # @param time [Integer] The duration of the Pomodoro session in seconds.
+    # @param _tag [String] A tag or label for the session, not used in the notification message on macOS.
+    # @return [void]
+    def run_mac_session(time, _tag)
+      notification_command = "osascript -e 'display notification \"Pomodoro session complete! Time for a break.\"'"
+      command = "sleep #{time} && afplay /System/Library/Sounds/Basso.aiff && tt stop 0 && #{notification_command} &"
+      pid = spawn(command)
+      Process.wait(pid)
+    end
   end
 end

data/lib/timet/database.rb

@@ -14,7 +14,8 @@ module Timet
     #
     # @param database_path [String] The path to the SQLite database file. Defaults to DEFAULT_DATABASE_PATH.
     #
-    # @return [void] This method does not return a value; it performs side effects such as initializing the database connection and creating the necessary tables.
+    # @return [void] This method does not return a value; it performs side effects such as initializing the database
+    # connection and creating the necessary tables.
     #
     # @example Initialize a new Database instance with the default path
     #   Database.new
@@ -22,7 +23,8 @@ module Timet
     # @example Initialize a new Database instance with a custom path
     #   Database.new('/path/to/custom.db')
     #
-    # @note The method creates a new SQLite3 database connection and initializes the necessary tables if they do not already exist.
+    # @note The method creates a new SQLite3 database connection and initializes the necessary tables if they
+    # do not already exist.
     def initialize(database_path = DEFAULT_DATABASE_PATH)
       @db = SQLite3::Database.new(database_path)
       create_table
@@ -31,7 +33,8 @@ module Timet
 
     # Creates the items table if it doesn't already exist.
     #
-    # @return [void] This method does not return a value; it performs side effects such as executing SQL to create the table.
+    # @return [void] This method does not return a value; it performs side effects such as executing SQL to
+    # create the table.
     #
     # @example Create the items table
     #   create_table
@@ -50,7 +53,8 @@ module Timet
 
     # Adds a new column named "notes" to the "items" table if it doesn't exist.
     #
-    # @return [void] This method does not return a value; it performs side effects such as executing SQL to add the column.
+    # @return [void] This method does not return a value; it performs side effects such as executing SQL to add
+    # the column.
     #
     # @example Add the notes column to the items table
     #   add_notes
@@ -73,7 +77,8 @@ module Timet
     # @param tag [String] The tag associated with the item.
     # @param notes [String] The notes associated with the item.
     #
-    # @return [void] This method does not return a value; it performs side effects such as executing SQL to insert the item.
+    # @return [void] This method does not return a value; it performs side effects such as executing SQL
+    # to insert the item.
     #
     # @example Insert a new item into the items table
     #   insert_item(1633072800, 'work', 'Completed task X')
@@ -89,7 +94,8 @@ module Timet
     # @param field [String] The field to be updated.
     # @param value [String, Integer, nil] The new value for the specified field.
     #
-    # @return [void] This method does not return a value; it performs side effects such as executing SQL to update the item.
+    # @return [void] This method does not return a value; it performs side effects such as executing SQL
+    # to update the item.
     #
     # @example Update the tag of an item with ID 1
     #   update_item(1, 'tag', 'updated_work')
@@ -105,7 +111,8 @@ module Timet
     #
     # @param id [Integer] The ID of the item to be deleted.
     #
-    # @return [void] This method does not return a value; it performs side effects such as executing SQL to delete the item.
+    # @return [void] This method does not return a value; it performs side effects such as executing SQL
+    # to delete the item.
     #
     # @example Delete an item with ID 1
     #   delete_item(1)
@@ -174,7 +181,8 @@ module Timet
     # @example Fetch all items from today
     #   all_items
     #
-    # @note The method executes SQL to fetch all items from the 'items' table that have a start time greater than or equal to today.
+    # @note The method executes SQL to fetch all items from the 'items' table that have a start time greater than
+    # or equal to today.
     def all_items
       execute_sql("SELECT * FROM items where start >= '#{Date.today.to_time.to_i}' ORDER BY id DESC")
     end
@@ -199,7 +207,8 @@ module Timet
 
     # Closes the database connection.
     #
-    # @return [void] This method does not return a value; it performs side effects such as closing the database connection.
+    # @return [void] This method does not return a value; it performs side effects such as closing the
+    # database connection.
     #
     # @example Close the database connection
     #   close
@@ -218,7 +227,8 @@ module Timet
     # @example Convert 3661 seconds to HH:MM:SS format
     #   seconds_to_hms(3661) # => '01:01:01'
     #
-    # @note The method converts the given number of seconds into hours, minutes, and seconds, and formats them as HH:MM:SS.
+    # @note The method converts the given number of seconds into hours, minutes, and seconds, and formats
+    # them as HH:MM:SS.
     def seconds_to_hms(seconds)
       hours, remainder = seconds.divmod(3600)
       minutes, seconds = remainder.divmod(60)

data/lib/timet/formatter.rb

@@ -6,7 +6,8 @@ module Timet
   module Formatter
     # Formats the header of the time tracking report table.
     #
-    # @return [void] This method does not return a value; it performs side effects such as printing the formatted header.
+    # @return [void] This method does not return a value; it performs side effects such as printing
+    # the formatted header.
     #
     # @example Format and print the table header
     #   format_table_header
@@ -14,9 +15,9 @@ 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
+        \033[32m| Id    | Date       | Tag    | Start    | End      | Duration | Notes              |\033[0m
         #{format_table_separator}
       TABLE
       puts header
@@ -27,11 +28,11 @@ module Timet
     # @return [String] The formatted separator line.
     #
     # @example Get the formatted table separator
-    #   format_table_separator # => '+-------+------------+--------+----------+----------+----------+--------------------------+'
+    #   format_table_separator # => '+-------+------------+--------+----------+----------+----------+------------+'
     #
     # @note The method returns a string representing the separator line for the table.
     def format_table_separator
-      '+-------+------------+--------+----------+----------+----------+--------------------------+'
+      '+-------+------------+--------+----------+----------+----------+--------------------+'
     end
 
     # Formats a row of the time tracking report table.
@@ -59,10 +60,140 @@ module Timet
     #
     # @note The method truncates the notes to a maximum of 20 characters and pads them to a fixed width.
     def format_notes(notes)
-      return ' ' * 23 if notes.nil?
+      spaces = 17
+      return ' ' * spaces if notes.nil?
 
-      notes = "#{notes.slice(0, 20)}..." if notes.length > 20
-      notes.ljust(23)
+      notes = "#{notes.slice(0, spaces - 3)}..." if notes.length > spaces - 3
+      notes.ljust(spaces)
+    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)
+      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 }
+      process_and_print_tags(sorted_duration_by_tag, factor, total)
+    end
+
+    # Processes and prints the tag distribution information.
+    #
+    # @param sorted_duration_by_tag [Array<Array(String, Numeric)>] An array of arrays where each inner array contains a
+    # tag and its corresponding duration, sorted by duration in descending order.
+    # @param factor [Numeric] The factor used to adjust the bar length.
+    # @param total [Numeric] The total duration of all tags combined.
+    # @return [void] This method outputs the tag distribution information to the standard output.
+    def process_and_print_tags(sorted_duration_by_tag, factor, total)
+      block = '▅'
+      sorted_duration_by_tag.each do |tag, duration|
+        value = (duration.to_f / total * 100).round(2)
+        bar_length = (value / factor).to_i
+        color = rand(256)
+        puts "#{tag.rjust(8)}: #{value.to_s.rjust(7)}%  \u001b[38;5;#{color}m#{block * bar_length}\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) }
+      print ']'
+      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
+      print ']'
+      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/status_helper.rb

@@ -7,7 +7,8 @@ module Timet
     #
     # @param result [Array] The result set containing time tracking items.
     #
-    # @return [Symbol] The status of the time tracking result. Possible values are :no_items, :in_progress, or :complete.
+    # @return [Symbol] The status of the time tracking result. Possible values are
+    # :no_items, :in_progress, or :complete.
     #
     # @example Determine the status of an empty result set
     #   StatusHelper.determine_status([]) # => :no_items

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

@@ -24,11 +24,13 @@ module Timet
     # Initializes a new instance of the TimeReport class.
     #
     # @param db [Database] The database instance to use for fetching data.
-    # @param filter [String, nil] The filter to apply when fetching items. Possible values include 'today', 'yesterday', 'week', 'month', or a date range in the format 'YYYY-MM-DD..YYYY-MM-DD'.
+    # @param filter [String, nil] The filter to apply when fetching items. Possible values include 'today',
+    # 'yesterday', 'week', 'month', or a date range in the format 'YYYY-MM-DD..YYYY-MM-DD'.
     # @param tag [String, nil] The tag to filter the items by.
     # @param csv [String, nil] The filename to use when exporting the report to CSV.
     #
-    # @return [void] This method does not return a value; it performs side effects such as initializing the instance variables.
+    # @return [void] This method does not return a value; it performs side effects such as initializing the
+    # instance variables.
     #
     # @example Initialize a new TimeReport instance with a filter and tag
     #   TimeReport.new(db, 'today', 'work', 'report.csv')
@@ -51,12 +53,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.
@@ -167,7 +180,7 @@ module Timet
       total = @items.map do |item|
         TimeHelper.calculate_duration(item[1], item[2])
       end.sum
-      puts "|#{' ' * 43}\033[94mTotal:  | #{@db.seconds_to_hms(total).rjust(8)} |\033[0m                          |"
+      puts "|#{' ' * 37}\033[94mTotal:  | #{@db.seconds_to_hms(total).rjust(8)} |\033[0m                          |"
       puts format_table_separator
     end
 

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.1.0'
-  VERSION = '1.1.0'
+  #   Timet::VERSION # => '1.2.1'
+  VERSION = '1.2.1'
 end

data/lib/timet.rb

@@ -2,7 +2,8 @@
 
 # Require the Timet::Application class from the 'timet/application' file.
 #
-# @note This statement loads the Timet::Application class, which is responsible for handling the command-line interface and user commands.
+# @note This statement loads the Timet::Application class, which is responsible for handling the command-line
+# interface and user commands.
 require_relative 'timet/application'
 
 # Require the Timet::Database class from the 'timet/database' file.
@@ -12,5 +13,6 @@ require_relative 'timet/database'
 
 # Require the Timet::TimeReport class from the 'timet/time_report' file.
 #
-# @note This statement loads the Timet::TimeReport class, which is responsible for displaying a report of tracked time entries.
+# @note This statement loads the Timet::TimeReport class, which is responsible for displaying a report
+# of tracked time entries.
 require_relative 'timet/time_report'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: timet
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Frank Vielma
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-09 00:00:00.000000000 Z
+date: 2024-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -89,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