timet 1.4.0 → 1.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bec76070c29c2eab4a2a5792084a9980c1cd29c0ab3ac80dbae2c6310e74d78a
-  data.tar.gz: 551fe37b00ac0ca015e28fcdd37810216c0ff00ea4b800c97bd0fb539af1df7b
+  metadata.gz: 9c57d8e7c61f25526dda2e7a5d1208814cadbc93192b7c60c342399c83f0b545
+  data.tar.gz: 625f4ba71e547e2ebb483d93f1de3812a8b075cacc7afaff7c80554267e5bcc1
 SHA512:
-  metadata.gz: 290e56a65e8c9e163d1558efe87fb93c8d74522c9aa1410f77a21ea6fe81d4a8270ec03947deb959699940c1c40ff91b4749f9512f1de4e005ac822cb564934a
-  data.tar.gz: 0e27f41ad71bca972355c70c235d900ae0c4ec571c47f9fd7324b979b3036b02f4cd6dd5aaa0464d4dd5ac12f2989ae38aed5e15613c496eb182dacb92f3bf11
+  metadata.gz: 99b2d1783c14024620865d826d11e16c42146ce220a50ae066cf762231129c42d683d88e4bb50086a5743cc923cdacd1d88f6fd4a4af4f5b5934017bfbb7b476
+  data.tar.gz: 7d3cb54c375f6fe2b86f0ffedb290d31c5d2348ec877a0848fc9c20d47c90422db6573a5ab0265ef4c0d8f6f89465dda7916f2f6dae59c2296511761b2f63705

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 ## [Unreleased]
 
+## [1.4.2] - 2024-11-01
+
+**Improvements:**
+
+- Refactored the `table` method in `lib/timet/table.rb` to simplify its return value and remove unnecessary complexity.
+- Updated the `process_time_entries` and `process_time_block_item` methods to streamline the processing of time entries and time block items.
+- Integrated the `TimeStatistics` class into the `TagDistribution` module to calculate and display detailed statistics for each tag.
+- Modified the `tag_distribution` method to use the `TimeStatistics` class for generating tag distribution information.
+- Updated the `display` method in `lib/timet/time_report.rb` to use the refactored methods and integrate the new tag distribution logic.
+- Added the `descriptive_statistics` gem to the Gemfile to support statistical calculations.
+- Created a new `TimeStatistics` class in `lib/timet/time_statistics.rb` to analyze and summarize time duration data associated with various tags.
+- Implemented methods in `TimeStatistics` to calculate total duration by tag, sorted duration by tag, average duration by tag, standard deviation by tag, and additional descriptive statistics by tag.
+- Updated Gemfile.lock to reflect the new dependency.
+- Update README.md
+
+**Tasks:**
+
+- Refactor time tracking report methods and integrate `TimeStatistics`.
+- Add `descriptive_statistics` gem and create `TimeStatistics` class.
+- Fix typo in `README.md`.
+
+**Bug fixes:**
+
+- Fixed a typo in `README.md`.
+
+## [1.4.1] - 2024-10-31
+
+**Improvements:**
+
+- Refactor `resume` method to accept an optional `id` parameter for resuming a specific tracking item.
+- Renamed `last_item_status` method to `item_status` in the `Database` class for better clarity and flexibility.
+- Updated `Application` class methods (`start`, `stop`, `resume`, `cancel`) to use the new `item_status` method.
+- Introduced `determine_status` method within the `Database` class to encapsulate status determination logic.
+- Updated documentation and test cases to reflect the changes and ensure consistent status handling.
+- Bumped version to reflect the changes.
+- Updated README.md to include new features and improvements.
+
+**Tasks:**
+
+- Refactor `resume` method.
+- Bump version.
+- Update README.md.
+- Refactor `Database` class for improved status determination and encapsulation.
+
 ## [1.4.0] - 2024-10-29
 
 **Improvements:**

data/README.md

@@ -7,23 +7,23 @@
 
 ![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](https://rubygems.org/gems/timet) is a command-line tool designed to track your activities by recording the time spent on each task. This allows 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.
 
 🔑 **Key Features:**
 
-- **Local Data Storage:** Timet utilizes SQLite to store your time tracking data locally, ensuring privacy and security.
+- **Local Data Storage:** Timet uses 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 specified range of dates, with bars in each column representing the amount of time tracked during that specific hour. The plot includes a header showing the hours and a row for each date, displaying the time blocks for each hour.
+- **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 specified range of dates. Each column represents the amount of time tracked during a specific hour, with a header showing the hours and a row for each date displaying the time blocks for each 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.
+- **Detailed Statistics:** Displays detailed statistics for each tag, including total duration, average duration, and standard deviation.
 
-
-Examples:
+**Examples:**
 
 ![Timet1 demo](timet1.gif)
 
@@ -32,10 +32,9 @@ Examples:
 - Ruby version: >= 3.0.0
 - sqlite3: > 1.7
 
-Old versions of Ruby and Sqlite:
+For older versions of Ruby and Sqlite:
 
 - [Ruby >= 2.7](https://github.com/frankvielma/timet/tree/ruby-2.7.0)
-
 - [Ruby >= 2.4](https://github.com/frankvielma/timet/tree/ruby-2.4.0)
 
 ## 💾 Installation
@@ -54,7 +53,8 @@ gem install timet
 - `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:
+
+- **`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
@@ -81,15 +81,15 @@ gem install timet
 
   The `pomodoro` option in the `start` command enhances time tracking by integrating the Pomodoro Technique. Users can specify a Pomodoro session length in minutes, like `pomodoro=25`, to start a 25-minute work interval. The app automatically tracks time and notifies users when the interval ends, helping maintain focus.
 
-  **Benefits**
+  **Benefits:**
 
-    - **Flexibility**: Supports various productivity strategies.
-    - **Focus**: Encourages disciplined work practices.
-    - **Productivity**: Helps achieve higher productivity and better time management.
+  - **Flexibility:** Supports various productivity strategies.
+  - **Focus:** Encourages disciplined work practices.
+  - **Productivity:** Helps achieve higher productivity and better time management.
 
 ---
 
-- **timet stop**: Stops tracking the current task, records the elapsed time, and displays the total time spent on all tasks.
+- **`timet stop`:** Stops tracking the current task, records the elapsed time, and displays the total time spent on all tasks.
 
   ```bash
   timet stop
@@ -105,8 +105,14 @@ gem install timet
   |                                           Total:  | 01:00:00 |                          |
   +-------+------------+--------+----------+----------+----------+--------------------------+
   ```
+
 ---
-- **timet resume**: It allows users to quickly resume tracking a task that was previously in progress.
+
+- **`timet resume [id]`:** This command allows users to quickly resume tracking a task that was previously in progress. If an ID is provided, it resumes the tracking session for the specified task. If no ID is provided, it resumes the last completed task.
+
+  ```bash
+  timet resume 1
+  ```
 
   ```
   Tracked time report [today]:
@@ -119,10 +125,12 @@ gem install timet
   |                                           Total:  | 01:00:00 |                          |
   +-------+------------+--------+----------+----------+----------+--------------------------+
   ```
+
 ---
-- **timet edit**: It allows users to update a task's notes, tag, start, or end fields. Users can either interactively select the field and provide a new value or specify them directly in the command.
 
-- **Interactive Mode:**
+- **`timet edit`:** Allows users to update a task's notes, tag, start, or end fields. Users can either interactively select the field and provide a new value or specify them directly in the command.
+
+  **Interactive Mode:**
 
   ```bash
   timet edit 1
@@ -145,7 +153,7 @@ gem install timet
     End
   ```
 
-- **Direct Specification Mode:**
+  **Direct Specification Mode:**
 
   ```bash
   timet e 1 notes "New Meeting Notes"
@@ -163,23 +171,23 @@ gem install timet
   +-------+------------+--------+----------+----------+----------+--------------------------+
   ```
 
-## 📋  Command Reference
+## 📋 Command Reference
 
-| Command                             | Description                                                                 | Example Usage                     |
-| ----------------------------------- | --------------------------------------------------------------------------- | --------------------------------- |
-| `timet start [tag] --notes=''  --pomodoro=[time]`   | Start tracking time for a task labeled [tag] and notes (optional).          | `timet start Task "My notes" 25`     |
-| `timet stop`                        | Stop tracking time.                                                         | `timet start Task "My notes"`     |
-| `timet summary today (t)`           | Display a report of tracked time for today.                                 | `timet su t` or `timet su`        |
-| `timet summary yesterday (y)`       | Display a report of tracked time for yesterday.                             | `timet su y`                      |
-| `timet summary week (w)`            | Display a report of tracked time for the week.                              | `timet su w`                      |
-| `timet summary month (m)`           | Resume tracking the last month.                                             | `timet su m`                      |
-| `timet su t --csv=[filename]`       | Display a report of tracked time for today and export it to `filename.csv`. | `timet su t --csv=file.csv`       |
-| `timet summary resume (r)`          | Resume tracking the last task.                                              | `timet su r`                      |
-| `timet delete [id]`                 | Delete a task by its ID.                                                    | `timet d [id]`                    |
-| `timet cancel`                      | Cancel active time tracking.                                                | `timet c`                         |
-| `timet edit [id]`                   | Update a task's notes, tag, start or end fields.                            | `timet e [1]`                     |
-| `timet su [date]`                   | Display a report of tracked time for a specific date.                       | `timet su 2024-01-03`             |
-| `timet su [start_date]..[end_date]` | Display a report of tracked time for a date range.                          | `timet su 2024-01-02..2024-01-03` |
+| Command                                      | Description                                                                 | Example Usage                     |
+| -------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------- |
+| `timet start [tag] --notes='' --pomodoro=[time]` | Start tracking time for a task labeled [tag] and notes (optional).          | `timet start Task "My notes" 25`     |
+| `timet stop`                                 | Stop tracking time.                                                         | `timet stop`                       |
+| `timet summary today (t)`                    | Display a report of tracked time for today.                                 | `timet su t` or `timet su`        |
+| `timet summary yesterday (y)`                | Display a report of tracked time for yesterday.                             | `timet su y`                      |
+| `timet summary week (w)`                     | Display a report of tracked time for the week.                              | `timet su w`                      |
+| `timet summary month (m)`                    | Display a report of tracked time for the month.                             | `timet su m`                      |
+| `timet su t --csv=[filename]`                | Display a report of tracked time for today and export it to `filename.csv`. | `timet su t --csv=file.csv`       |
+| `timet delete [id]`                          | Delete a task by its ID.                                                    | `timet d [id]`                    |
+| `timet cancel`                               | Cancel active time tracking.                                                | `timet c`                         |
+| `timet edit [id]`                            | Update a task's notes, tag, start, or end fields.                           | `timet e [id]`                    |
+| `timet su [date]`                            | Display a report of tracked time for a specific date.                       | `timet su 2024-01-03`             |
+| `timet su [start_date]..[end_date]`          | Display a report of tracked time for a date range.                          | `timet su 2024-01-02..2024-01-03` |
+| `timet resume (r) [id]`                      | Resume tracking a task by ID or the last completed task.                    | `timet resume [id]`               |
 
 ### Date Range in Summary
 
@@ -187,20 +195,21 @@ The `timet summary` command now supports specifying a date range for generating
 
 #### Examples:
 
-- **Single Date**: Display a report for a specific date.
+- **Single Date:** Display a report for a specific date.
 
   ```sh
   timet su 2024-01-03
   ```
 
-- **Date Range**: Display a report for a date range.
+- **Date Range:** Display a report for a date range.
+
   ```sh
   timet su 2024-01-02..2024-01-03
   ```
 
 ## Data
 
-Timet's data is stored in ~/.timet.db
+Timet's data is stored in `~/.timet.db`.
 
 ## Development
 
@@ -210,13 +219,14 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/frankvielma/timet. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/frankvielma/timet/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at [https://github.com/frankvielma/timet](https://github.com/frankvielma/timet). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/frankvielma/timet/blob/master/CODE_OF_CONDUCT.md).
 
 ## Buy Me A Coffee! ☕
 
 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
 ```
@@ -231,4 +241,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Timet project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/frankvielma/timet/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Timet project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/frankvielma/timet/blob/master/CODE_OF_CONDUCT.md).

data/lib/timet/application.rb

@@ -69,9 +69,7 @@ module Timet
       notes = options[:notes] || notes
       pomodoro = (options[:pomodoro] || pomodoro).to_i
 
-      unless VALID_STATUSES_FOR_INSERTION.include?(@db.last_item_status)
-        return puts 'A task is currently being tracked.'
-      end
+      return puts 'A task is currently being tracked.' unless VALID_STATUSES_FOR_INSERTION.include?(@db.item_status)
 
       @db.insert_item(start_time, tag, notes, pomodoro)
       play_sound_and_notify(pomodoro * 60, tag) if pomodoro.positive?
@@ -87,13 +85,13 @@ module Timet
     # @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 The method checks if the last tracking item is in progress by calling `@db.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.
     def stop(display = nil)
-      return unless @db.last_item_status == :in_progress
+      return unless @db.item_status == :in_progress
 
       last_id = @db.fetch_last_id
       @db.update_item(last_id, 'end', TimeHelper.current_timestamp)
@@ -101,7 +99,7 @@ module Timet
       summary unless display
     end
 
-    desc 'resume (r)', 'resume last task'
+    desc 'resume (r) [id]', '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
@@ -110,23 +108,26 @@ module Timet
     # @example Resume the last tracking session
     #   resume
     #
-    # @note The method checks the status of the last tracking item using `@db.last_item_status`.
+    # @example Resume a specific task by ID
+    #   resume(123)
+    #
+    # @note The method checks the status of the last tracking item using `@db.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,
+    # @note If the last item is complete, it fetches the last item using `@db.find_item` or `@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
-
-      case status
+    #
+    # @param id [Integer, nil] The ID of the tracking item to resume. If nil, the last item is used.
+    #
+    # @see Database#item_status
+    # @see Database#find_item
+    # @see #start
+    def resume(id = nil)
+      case @db.item_status(id)
       when :in_progress
         puts 'A task is currently being tracked.'
       when :complete
-        last_item = @db.last_item
-        if last_item
-          tag = last_item[FIELD_INDEX['tag']]
-          notes = last_item[FIELD_INDEX['notes']]
-          start(tag, notes)
-        end
+        resume_complete_task(id)
       end
     end
 
@@ -247,13 +248,13 @@ module Timet
     #   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 It checks if the last item is in progress by comparing `@db.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 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
-      return puts 'There is no active time tracking' if @db.last_item_status == :complete
+      return puts 'There is no active time tracking' if @db.item_status == :complete
 
       delete_item_and_print_message(id, "Canceled active time tracking #{id}")
     end

data/lib/timet/application_helper.rb

@@ -157,5 +157,32 @@ module Timet
       @db.delete_item(id)
       puts message
     end
+
+    # Resumes a tracking session for a completed task.
+    #
+    # @param id [Integer, nil] The ID of the tracking item to resume. If nil, the last completed item is used.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as resuming a tracking session.
+    #
+    # @example Resume the last completed task
+    #   resume_complete_task
+    #
+    # @example Resume a specific task by ID
+    #   resume_complete_task(123)
+    #
+    # @note The method fetches the specified or last completed item using `@db.find_item` or `@db.last_item`.
+    # @note If the item is found, it retrieves the tag and notes and calls the `start` method to resume the
+    # tracking session.
+    #
+    # @see Database#find_item
+    # @see Database#last_item
+    # @see #start
+    def resume_complete_task(id)
+      item = id ? @db.find_item(id) : @db.last_item
+      return unless item
+
+      tag, notes = item.values_at(Application::FIELD_INDEX['tag'], Application::FIELD_INDEX['notes'])
+      start(tag, notes)
+    end
   end
 end

data/lib/timet/database.rb

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
 
 require 'sqlite3'
-require_relative 'status_helper'
 module Timet
   # Provides database access for managing time tracking data.
   class Database
-    include StatusHelper
-
     # The default path to the SQLite database file.
     DEFAULT_DATABASE_PATH = File.join(Dir.home, '.timet.db')
 
@@ -158,12 +155,15 @@ module Timet
     # @return [Symbol] The status of the last item. Possible values are :no_items, :in_progress, or :complete.
     #
     # @example Determine the status of the last item
-    #   last_item_status
+    #   item_status
     #
     # @note The method executes SQL to fetch the last item and determines its status using the `StatusHelper` module.
-    def last_item_status
-      result = execute_sql('SELECT id, end FROM items ORDER BY id DESC LIMIT 1')
-      StatusHelper.determine_status(result)
+    #
+    # @param id [Integer, nil] The ID of the item to check. If nil, the last item in the table is used.
+    #
+    def item_status(id = nil)
+      id = fetch_last_id if id.nil?
+      determine_status(find_item(id))
     end
 
     # Finds an item in the items table by its ID.
@@ -241,5 +241,33 @@ module Timet
 
       format '%<hours>02d:%<minutes>02d:%<seconds>02d', hours: hours, minutes: minutes, seconds: seconds
     end
+
+    # Determines the status of a time tracking result based on the presence and end time of items.
+    #
+    # @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.
+    #
+    # @example Determine the status of an empty result set
+    #   StatusHelper.determine_status([]) # => :no_items
+    #
+    # @example Determine the status of a result set with an in-progress item
+    #   StatusHelper.determine_status([[1, nil]]) # => :in_progress
+    #
+    # @example Determine the status of a result set with a completed item
+    #   StatusHelper.determine_status([[1, 1633072800]]) # => :complete
+    #
+    # @note The method checks if the result set is empty and returns :no_items if true.
+    # @note If the last item in the result set has no end time, it returns :in_progress.
+    # @note If the last item in the result set has an end time, it returns :complete.
+    def determine_status(result)
+      return :no_items if result.nil?
+
+      last_item_end = result[2]
+      return :in_progress unless last_item_end
+
+      :complete
+    end
   end
 end

data/lib/timet/table.rb

@@ -9,12 +9,12 @@ module Timet
     # @example
     #   table
     #
-    # @return [Array<(String, Hash)>] An array containing the time block string and a hash of durations by tag.
+    # @return [String] The time block string.
     #
     # @note
     #   - The method relies on the `header`, `process_time_entries`, `separator`, and `total` methods.
     #   - The `header` method is responsible for printing the table header.
-    #   - The `process_time_entries` method processes the time entries and returns the time block and duration by tag.
+    #   - The `process_time_entries` method processes the time entries and returns the time block.
     #   - The `separator` method returns a string representing the separator line.
     #   - The `total` method prints the total duration.
     #
@@ -24,10 +24,10 @@ module Timet
     # @see #total
     def table
       header
-      time_block, duration_by_tag = process_time_entries
+      time_block = process_time_entries
       puts separator
       total
-      [time_block, duration_by_tag]
+      time_block
     end
 
     # Formats the header of the time tracking report table.
@@ -62,73 +62,53 @@ module Timet
       '+-------+------------+--------+----------+----------+----------+--------------------+'
     end
 
-    # Processes each time entry in the `items` array and updates the time block and duration by tag.
+    # Processes time entries and generates a time block structure.
     #
-    # @return [Array<(Hash, Hash)>] An array containing the updated time block and duration by tag.
-    #
-    # @example
-    #   items = [
-    #     [start_time1, end_time1, tag1],
-    #     [start_time2, end_time2, tag2]
-    #   ]
-    #   process_time_entries
-    #   #=> [{ '2024-10-21' => { 8 => [duration1, tag1], 9 => [duration2, tag2] } },
-    #   { tag1 => total_duration1, tag2 => total_duration2 }]
+    # @return [Hash] A nested hash representing the time block structure.
     #
     # @note
-    #   - The method relies on the `items` instance variable, which should be an array of arrays.
-    #   - Each sub-array in `items` is expected to contain a start time, end time, and a tag.
-    #   - The `display_time_entry` method is used to display each time entry.
-    #   - The `process_time_block_item` method processes each time entry and updates the time block and duration by tag.
+    #   - The method iterates over each item in the `items` array.
+    #   - For each item, it calls `display_time_entry` to display the time entry.
+    #   - It then processes the time block item using `process_time_block_item`.
+    #   - The `TimeHelper.extract_date` method is used to extract the date from the items.
     #
-    # @see #items
     # @see #display_time_entry
     # @see #process_time_block_item
+    # @see TimeHelper#extract_date
     def process_time_entries
-      duration_by_tag = Hash.new(0)
       time_block = Hash.new { |hash, key| hash[key] = {} }
 
       items.each_with_index do |item, idx|
         display_time_entry(item, TimeHelper.extract_date(items, idx))
-        time_block, duration_by_tag = process_time_block_item(item, time_block, duration_by_tag)
+        time_block = process_time_block_item(item, time_block)
       end
-      [time_block, duration_by_tag]
+
+      time_block
     end
 
-    # Processes a time block item and updates the time block hash.
+    # Processes a single time block item and updates the time block structure.
     #
-    # @param item [Array] The time entry to process, containing the start time, end time, and tag.
-    # @param time_block [Hash] A hash containing time block data, where keys are dates and values are hashes of time
-    # slots and their corresponding values.
-    # @param duration_by_tag [Hash] A hash containing the total duration by tag.
+    # @param item [Array] An array containing the item details, including start time, end time, and tag.
+    # @param time_block [Hash] The current time block structure.
     #
-    # @return [Array<(Hash, Hash)>] An array containing the updated time block hash and the updated duration
-    # by tag hash.
-    #
-    # @example
-    #   item = [nil, Time.new(2024, 10, 21, 8, 0, 0), Time.new(2024, 10, 21, 9, 0, 0), 'work']
-    #   time_block = {}
-    #   duration_by_tag = {}
-    #   process_time_block_item(item, time_block, duration_by_tag)
-    #   #=> [{ '2024-10-21' => { 8 => [3600, 'work'] } }, { 'work' => 3600 }]
+    # @return [Hash] The updated time block structure.
     #
     # @note
-    #   - The method relies on the `TimeHelper` module for time-related calculations.
-    #   - The `add_hashes` method is used to merge the new time block data into the existing time block hash.
-    #   - The `calculate_duration` method calculates the duration between the start and end times.
+    #   - The method extracts the start time, end time, and tag from the item.
+    #   - It calculates the number of seconds per hour block using `TimeHelper.count_seconds_per_hour_block`.
+    #   - It converts the start time to a date using `TimeHelper.timestamp_to_date`.
+    #   - It updates the time block structure by adding the new block hour to the existing structure.
     #
     # @see TimeHelper#count_seconds_per_hour_block
     # @see TimeHelper#timestamp_to_date
-    # @see TimeHelper#calculate_duration
     # @see #add_hashes
-    def process_time_block_item(item, time_block, duration_by_tag)
+    def process_time_block_item(item, time_block)
       _, start_time, end_time, tag = item
 
       block_hour = TimeHelper.count_seconds_per_hour_block(start_time, end_time, tag)
       date_line = TimeHelper.timestamp_to_date(start_time)
       time_block[date_line] = add_hashes(time_block[date_line], block_hour)
-      duration_by_tag[tag] += TimeHelper.calculate_duration(start_time, end_time)
-      [time_block, duration_by_tag]
+      time_block
     end
 
     # Displays a single time entry in the report.

data/lib/timet/tag_distribution.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'time_statistics'
 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
@@ -12,20 +13,23 @@ module Timet
     # 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 }
-    #   Formatter.format_tag_distribution(duration_by_tag)
+    #   colors = { "timet" => "\e[31m", "nextjs" => "\e[32m" }
+    #   Formatter.format_tag_distribution(duration_by_tag, colors)
     #   # Output:
-    #   #  timet:   66.67%  ====================
-    #   #  nextjs:   33.33%  ==========
-    def tag_distribution(duration_by_tag, colors)
-      total = duration_by_tag.values.sum
+    #   #  \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
+
       return unless total.positive?
 
-      sorted_duration_by_tag = duration_by_tag.sort_by { |_, duration| -duration }
-      process_and_print_tags(sorted_duration_by_tag, total, colors)
+      process_and_print_tags(time_stats, total, colors)
     end
 
     # Processes and prints the tag distribution information.
@@ -34,15 +38,50 @@ module Timet
     # tag and its corresponding duration, sorted by duration in descending order.
     # @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, total, colors)
-      sorted_duration_by_tag.each do |tag, duration|
-        value, bar_length = calculate_value_and_bar_length(duration, total)
-        horizontal_bar = (BLOCK_CHAR * bar_length).to_s.color(colors[tag] + 1)
-        tag = tag[0..TAG_SIZE - 1] if tag.size >= TAG_SIZE
-        puts "#{tag.rjust(TAG_SIZE)}: #{value.to_s.rjust(5)}%  #{horizontal_bar}"
+    def process_and_print_tags(time_stats, total, colors)
+      time_stats.sorted_duration_by_tag.each do |tag, duration|
+        print_tag_info(tag, duration, total, time_stats, colors)
       end
     end
 
+    # Prints the detailed information for a specific tag.
+    #
+    # @param tag [String] The tag for which to print the information.
+    # @param duration [Numeric] The duration associated with the tag.
+    # @param total [Numeric] The total duration of all tags combined.
+    # @param time_stats [Object] An object containing time statistics for the tags.
+    # @param colors [Hash] A hash mapping tags to color indices for display.
+    # @return [void] This method outputs the tag information to the standard output.
+    def print_tag_info(tag, duration, total, time_stats, colors)
+      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}]"
+    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)
+    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
+    end
+
     # Calculates the percentage value and bar length for a given duration and total duration.
     #
     # @param duration [Numeric] The duration for the current tag.
@@ -53,7 +92,7 @@ module Timet
     #   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 = (duration.to_f / total * 100).round(2)
+      percentage_value = (duration.to_f / total * 100).round(1)
       bar_length = (value * MAX_BAR_LENGTH).round
       [percentage_value, bar_length]
     end

data/lib/timet/time_report.rb

@@ -54,15 +54,22 @@ module Timet
     #   time_report.display
     #
     # @note The method formats and prints the table header, rows, and total duration.
+    #
+    # @param items [Array<Hash>] The list of time entries to be displayed.
+    # @param options [Hash] Additional options for customizing the display (e.g., color scheme).
+    #
+    # @see #table
+    # @see #print_time_block_chart
+    # @see #tag_distribution
     def display
-      return puts 'No tracked time found for the specified filter.' if items.empty?
+      return puts 'No tracked time found for the specified filter.' if @items.empty?
 
-      time_block, duration_by_tag = table
+      time_block = table
 
-      colors = duration_by_tag.map { |x| x[0] }.sort.each_with_index.to_h
+      colors = @items.map { |x| x[3] }.uniq.each_with_index.to_h
       print_time_block_chart(time_block, colors)
 
-      tag_distribution(duration_by_tag, colors)
+      tag_distribution(colors)
     end
 
     # Displays a single row of the report.

data/lib/timet/time_statistics.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'descriptive_statistics'
+require_relative 'time_helper'
+
+module Timet
+  # @!attribute [r] duration_by_tag
+  #   @return [Hash] A hash where keys are tags and values are arrays of durations (in seconds) associated
+  #   with each tag.
+  # @!attribute [r] total_duration
+  #   @return [Integer] The total duration (in seconds) of all time intervals across all tags.
+  class TimeStatistics
+    attr_reader :duration_by_tag, :total_duration
+
+    # Initializes a new instance of TimeStatistics.
+    #
+    # @param data [Array<Array>] An array of arrays where each sub-array contains:
+    #   - [0] An identifier (not used in calculations)
+    #   - [1] The start time (in seconds since the epoch)
+    #   - [2] The end time (in seconds since the epoch), or nil if the interval is ongoing
+    #   - [3] The tag associated with the time interval
+    # @return [TimeStatistics] A new instance of TimeStatistics.
+    def initialize(data)
+      @data = data
+      @duration_by_tag = Hash.new { |hash, key| hash[key] = [] }
+      @total_duration = 0
+      calculate_durations_by_tag
+    end
+
+    # Calculates the duration for each tag and updates the @duration_by_tag and @total_duration attributes.
+    #
+    # @return [void]
+    def calculate_durations_by_tag
+      @data.each do |row|
+        start_time = row[1]
+        end_time = row[2] || Time.now.to_i
+        tag = row[3]
+
+        duration = end_time - start_time
+        @duration_by_tag[tag] << duration
+        @total_duration += duration
+      end
+    end
+
+    # Returns a hash where keys are tags and values are the total duration (in seconds) for each tag.
+    #
+    # @return [Hash<String, Integer>] A hash mapping tags to their total durations.
+    def total_duration_by_tag
+      @duration_by_tag.transform_values(&:sum)
+    end
+
+    # Returns an array of arrays where each sub-array contains a tag and its total duration, sorted by duration in
+    # descending order.
+    #
+    # @return [Array<Array>] An array of [tag, total_duration] pairs sorted by total_duration in descending order.
+    def sorted_duration_by_tag
+      @duration_by_tag.map { |tag, durations| [tag, durations.sum] }.sort_by { |_, sum| -sum }
+    end
+
+    # Returns a hash where keys are tags and values are the average duration (in seconds) for each tag.
+    #
+    # @return [Hash<String, Float>] A hash mapping tags to their average durations.
+    def average_by_tag
+      @duration_by_tag.transform_values { |durations| durations.sum.to_f / durations.size }
+    end
+
+    # Returns a hash where keys are tags and values are the standard deviation of durations for each tag.
+    #
+    # @return [Hash<String, Float>] A hash mapping tags to their standard deviations.
+    def standard_deviation_by_tag
+      @duration_by_tag.transform_values(&:standard_deviation)
+    end
+
+    # Returns a hash where keys are tags and values are additional descriptive statistics for the durations of each tag.
+    #
+    # @return [Hash<String, Hash>] A hash mapping tags to a hash of descriptive statistics
+    # (e.g., min, max, median, etc.).
+    def additional_stats_by_tag
+      @duration_by_tag.transform_values(&:descriptive_statistics)
+    end
+  end
+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.4.0'
-  VERSION = '1.4.0'
+  #   Timet::VERSION # => '1.4.2'
+  VERSION = '1.4.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: timet
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.4.2
 platform: ruby
 authors:
 - Frank Vielma
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-29 00:00:00.000000000 Z
+date: 2024-11-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -82,13 +82,13 @@ files:
 - lib/timet/application_helper.rb
 - lib/timet/color_codes.rb
 - lib/timet/database.rb
-- lib/timet/status_helper.rb
 - lib/timet/table.rb
 - lib/timet/tag_distribution.rb
 - lib/timet/time_block_chart.rb
 - lib/timet/time_helper.rb
 - lib/timet/time_report.rb
 - lib/timet/time_report_helper.rb
+- lib/timet/time_statistics.rb
 - lib/timet/validation_edit_helper.rb
 - lib/timet/version.rb
 - sig/timet.rbs

data/lib/timet/status_helper.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-module Timet
-  # Provides helper methods to determine the status of time tracking results.
-  module StatusHelper
-    # Determines the status of a time tracking result based on the presence and end time of items.
-    #
-    # @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.
-    #
-    # @example Determine the status of an empty result set
-    #   StatusHelper.determine_status([]) # => :no_items
-    #
-    # @example Determine the status of a result set with an in-progress item
-    #   StatusHelper.determine_status([[1, nil]]) # => :in_progress
-    #
-    # @example Determine the status of a result set with a completed item
-    #   StatusHelper.determine_status([[1, 1633072800]]) # => :complete
-    #
-    # @note The method checks if the result set is empty and returns :no_items if true.
-    # @note If the last item in the result set has no end time, it returns :in_progress.
-    # @note If the last item in the result set has an end time, it returns :complete.
-    def self.determine_status(result)
-      return :no_items if result.empty?
-
-      last_item_end = result.first[1]
-      return :in_progress unless last_item_end
-
-      :complete
-    end
-  end
-end