timet 0.8.2 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5eda40ea4aafce60dc6fef1270ca9d013724c45b29ba43e7974b8212f55ac231
-  data.tar.gz: b5a45e366bbfdb073ccf32ad545b572faac79f018c3a6f8eac60622aed96b02b
+  metadata.gz: 7b90eeedf6f1653e70f0d90fc2181ebeec88c3788bbc88dbcd072f5a6f2fe821
+  data.tar.gz: c2fbc67fd45bb9d3923a91f737f03fc2a74599193cbe932fbeaadbb44a2d21be
 SHA512:
-  metadata.gz: 0d0cc2dfa64d2af724b2be8543d67f63f5485c4fe81746a29cea29db9b51d1ba5fcf4df98f7cdadb16961f30cd24dff0e65bef93c6f297fe9b61bc9a07b0e15e
-  data.tar.gz: fdd6364f4dad16defed0c484eb29adf27479427387be6cd43587bcdbfb628eea2a99a0712c708a5821e50e1064c476b2481cd2efc49cb302d533b0d632c3f08a
+  metadata.gz: 475f77e1febf29ccdb1e17bfdd309a829b3d309d4d670afe95ede0926ab897173006ab89d165de4f87c3c3663c5114a08e54ada2f6835453fc4d99fb86134c62
+  data.tar.gz: ca865940ccafb9e60eb682d9085202e3946e1029f5df01b0ece8e998d9dcbe3746f1a196d4638e9a94cb587425198cba4fd93182e2934185d4e849407d34f81c

data/CHANGELOG.md

@@ -1,23 +1,69 @@
 ## [Unreleased]
 
+## [0.9.1] - 2024-10-04
+
+**Improvements:**
+
+- Added YARD documentation
+- Refactored the `start` method to use `@db.insert_item` directly if the last item status is valid for insertion.
+- Removed the `insert_item_if_valid` private method as it is no longer needed.
+- Updated the README.md to reflect the latest changes and improvements.
+- Added a badge displaying the current gem version in the README.md.
+
+## [0.9.0] - 2024-10-03
+
+**Improvements:**
+
+- Enhanced the gemspec metadata by adding a documentation URI for better discoverability and reference.
+- Improved the `summary` and `edit` methods for better readability and functionality.
+- Simplified the `summary` method by using safe navigation operators and improved conditional checks.
+- Modified the `edit` method to use the return value of `validate_and_update` for displaying the updated item.
+- Updated the `validate_and_update` method to return the updated item after performing the update.
+- Enhanced the `TimeReport` class and added comprehensive RSpec tests.
+- Enhanced the `filter_items` method to support valid date range filters.
+- Added a `valid_date_format?` method to validate date formats.
+- Updated the `formatted_filter` method to handle valid date range filters.
+- Removed the `helpers.rb` file as it was no longer needed.
+- Added comprehensive RSpec tests for the `TimeReport` class, covering initialization, filtering, and date format validation.
+- Modified the `stop` method in `Timet::Application` to use the `update_item` method from `Database` instead of the deprecated `update` method.
+- Updated the `stop` method to fetch the last item's ID and update the 'end' field directly.
+- Updated test cases in `application_spec.rb` to reflect the changes in the `stop` method.
+- Removed test cases for the deprecated `update` method in `database_spec.rb`.
+
+**Bug fixes:**
+
+- Fix bug in calculate_end_time method
+
+**Additional Considerations:**
+
+- The changes in this PR aim to improve code quality, maintainability, and test coverage.
+- The removal of the `helpers.rb` file and unused methods helps to streamline the codebase and reduce technical debt.
+- The updated `stop` method now uses the `update_item` method, ensuring consistency across the codebase.
+- Comprehensive tests have been added for the `TimeReport` class to ensure robust functionality and prevent regressions.
+
 ## [0.8.2] - 2024-10-02
 
 **Improvements:**
+
 - Added optional field and new_value parameters to the edit command.
 - Updated the edit method logic to prompt for field and new_value if they are not provided.
 - Enhanced test coverage to include scenarios where field and new_value are provided directly and when they are not.
 - Updated the README to reflect the new features of the edit command, including both interactive and direct specification modes.
 
 **Additional Considerations:**
+
 - The changes ensure that the edit command is more versatile and user-friendly, catering to both interactive users and those who prefer scripting or automation.
 
 ## [0.8.1] - 2024-10-02
+
 **Bug fixes:**
-  - Fixed a LoadError caused by the byebug gem being required after its removal.
+
+- Fixed a LoadError caused by the byebug gem being required after its removal.
 
 ## [0.8.0] - 2024-10-01
 
 **Improvements:**
+
 - Introduced TimeHelper module to encapsulate time-related functionalities.
 - Replaced direct calls to Time.now.to_i with TimeHelper.current_timestamp for consistency and modularity.
 - Moved current_timestamp method to TimeHelper to centralize time-related logic.
@@ -50,6 +96,7 @@
 - Added a confirmation message when the CSV file is successfully exported.
 
 **Bug fixes:**
+
 - Updated timestamp_to_time method to return nil if the input timestamp is nil.
 - Removed unnecessary &.then syntax for clarity and consistency.
 - Corrected the test expectations to use the correct Unix timestamp.
@@ -61,6 +108,7 @@
 - Added validation to prevent updating start or end times with nil values.
 
 **Tasks:**
+
 - Added ENV['TZ'] = 'UTC' to spec_helper.rb to ensure that all RSpec tests run in the UTC time zone.
 - Updated tests to reflect the new structure and ensure items are returned for export.
 - Updated and added tests to cover the new export logic.
@@ -78,6 +126,7 @@
 - Updated database_spec.rb to reflect the correct status for in-progress items.
 
 **Additional Considerations:**
+
 - Ensured that all timestamps are handled in UTC to avoid timezone issues across different environments.
 - Updated the test to reflect the correct UTC time zone.
 - Ensured consistency in timestamp handling across methods.
@@ -85,6 +134,7 @@
 - Made the application easier to maintain and extend in the future.
 
 **Refactor and enhance time formatting methods**
+
 - Refactored `format_time_string` method in `TimeHelper` to improve readability and maintainability.
 - Added detailed documentation for the `format_time_string` method.
 - Simplified the logic for parsing and validating time components.
@@ -96,31 +146,30 @@
 
 ## [0.2.2] - 2024-09-27
 
-* **Improvements**:
-    * Updated SQLite3 gem version to 2.1.0
+- **Improvements**:
+  - Updated SQLite3 gem version to 2.1.0
 
 ## [0.2.1] - 2024-09-24
 
-* **Improved `resume` behavior:**
-    * If no notes are provided, it will attempt to retrieve them from the last tracked task.
-* **Enhanced `export_sheet` functionality:**
-    * A new `notes` column has been added to the exported CSV file.
-* **Minor bug fixes:**
-    * Resolved issues related to resuming tasks with notes and deleting items.
-
+- **Improved `resume` behavior:**
+  - If no notes are provided, it will attempt to retrieve them from the last tracked task.
+- **Enhanced `export_sheet` functionality:**
+  - A new `notes` column has been added to the exported CSV file.
+- **Minor bug fixes:**
+  - Resolved issues related to resuming tasks with notes and deleting items.
 
 ## [0.2.0] - 2024-09-24
 
-* **Improved code quality:**
-    * Enforces consistent quoting style with `RuboCop` integration.
-    * Removes unused gems (`mini_portile2`) from the `Gemfile`.
-* **Database enhancements:**
-    * Adds a new column named "notes" to the `items` table to store additional information about tracked time entries.
-* **Command-line improvements:**
-    * Allows adding notes to a new time entry using the `start` command with the `--notes` option (e.g., `timet start work --notes="meeting with client"`).
-    * Improves formatting and clarity of some command descriptions.
-* **General code formatting:**
-    * Uses single quotes (`'`) for strings and source paths in the `Gemfile`.
+- **Improved code quality:**
+  - Enforces consistent quoting style with `RuboCop` integration.
+  - Removes unused gems (`mini_portile2`) from the `Gemfile`.
+- **Database enhancements:**
+  - Adds a new column named "notes" to the `items` table to store additional information about tracked time entries.
+- **Command-line improvements:**
+  - Allows adding notes to a new time entry using the `start` command with the `--notes` option (e.g., `timet start work --notes="meeting with client"`).
+  - Improves formatting and clarity of some command descriptions.
+- **General code formatting:**
+  - Uses single quotes (`'`) for strings and source paths in the `Gemfile`.
 
 ## [0.1.0] - 2024-08-01
 

data/README.md

@@ -1,10 +1,11 @@
+[![Gem Version](https://badge.fury.io/rb/timet.svg)](https://badge.fury.io/rb/timet)
 ![timet workflow](https://github.com/frankvielma/timet/actions/workflows/ci.yml/badge.svg)
 [![Maintainability](https://api.codeclimate.com/v1/badges/44d57b6c561b9be717f5/maintainability)](https://codeclimate.com/github/frankvielma/timet/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/44d57b6c561b9be717f5/test_coverage)](https://codeclimate.com/github/frankvielma/timet/test_coverage)
 
 # Timet
 
-Timet is a command line time tracking with reports. It's simple to track your hours for work with Timet, whether you're curious about how you allocate your time.
+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.
 
@@ -150,6 +151,24 @@ gem install timet
 | `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`            |
+
+
+### Date Range in Summary
+
+The `timet summary` command now supports specifying a date range for generating reports. This allows users to filter and summarize data within specific date intervals. The date format is in ISO 8601 format (YYYY-MM-DD).
+
+#### Examples:
+- **Single Date**: Display a report for a specific date.
+  ```sh
+  timet su 2024-01-03
+  ```
+
+- **Date Range**: Display a report for a date range.
+  ```sh
+  timet su 2024-01-02..2024-01-03
+  ```
 
 
 ## Data

data/lib/timet/application.rb

@@ -19,10 +19,11 @@ module Timet
   class Application < Thor
     include ValidationEditHelper
     include ApplicationHelper
+    include TimeHelper
 
     def initialize(*args)
       super
-      @db = Timet::Database.new
+      @db = Database.new
     end
 
     FIELD_INDEX = {
@@ -34,20 +35,47 @@ module Timet
 
     VALID_STATUSES_FOR_INSERTION = %i[no_items complete].freeze
 
-    desc "start [tag] --notes='...'", "start time tracking  --notes='my notes...'"
+    desc "start [tag] --notes=''", "start time tracking  --notes='my notes...'"
     option :notes, type: :string, desc: 'Add a note'
+    # Starts a new tracking session with the given tag and optional notes.
+    #
+    # @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]`.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as inserting a tracking item and generating a summary.
+    #
+    # @example Start a tracking session with a tag and notes
+    #   start('work', 'Starting work on project X')
+    #
+    # @example Start a tracking session with only a tag
+    #   start('break')
+    #
+    # @note The method uses `TimeHelper.current_timestamp` to get the current timestamp for the start time.
+    # @note The method calls `summary` to generate a summary after inserting the tracking item.
     def start(tag, notes = nil)
       start_time = TimeHelper.current_timestamp
       notes = options[:notes] || notes
 
-      insert_item_if_valid(start_time, tag, notes)
+      @db.insert_item(start_time, tag, notes) if VALID_STATUSES_FOR_INSERTION.include?(@db.last_item_status)
       summary
     end
 
     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.
+    #
+    # @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.
     def stop
-      stop = TimeHelper.current_timestamp
-      @db.update(stop) if @db.last_item_status == :in_progress
+      if @db.last_item_status == :in_progress
+        last_id = @db.fetch_last_id
+        @db.update_item(last_id, 'end', TimeHelper.current_timestamp)
+      end
       result = @db.last_item
 
       return unless result
@@ -56,6 +84,16 @@ module Timet
     end
 
     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.
+    #
+    # @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.
     def resume
       status = @db.last_item_status
 
@@ -73,22 +111,62 @@ module Timet
     end
 
     desc 'summary (su) [filter] [tag] --csv=csv_filename',
-         "Display a summary of tracked time filter => [today (t), yesterday (y), week (w), month (m)] [tag]
-          and export to 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.
+    #
+    # @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.
+    #
+    # @example Generate a summary for today
+    #   summary('today')
+    #
+    # @example Generate a summary for a specific tag
+    #   summary(nil, 'work')
+    #
+    # @example Generate a summary for a date range and export to CSV
+    #   summary('2023-01-01..2023-01-31', nil, csv: 'summary.csv')
+    #
+    # @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 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('.')[0] if options[:csv]
+      csv_filename = options[:csv]&.split('.')&.first
       summary = TimeReport.new(@db, filter, tag, csv_filename)
+
       summary.display
-      if csv_filename && summary.items.any?
+      items = summary.items
+      if csv_filename && items.any?
         summary.export_sheet
-      elsif summary.items.empty?
+      elsif items.empty?
         puts 'No items found to export'
       end
     end
 
     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.
+    #
+    # @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.
+    #
+    # @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')
+    #
+    # @example Edit a tracking item with ID 2, prompting for the field and new value
+    #   edit(2)
+    #
+    # @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 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)
       item = @db.find_item(id)
       return puts "No tracked time found for id: #{id}" unless item
@@ -99,12 +177,24 @@ module Timet
         new_value = prompt_for_new_value(item, field)
       end
 
-      validate_and_update(item, field, new_value)
-
-      summary.display
+      updated_item = validate_and_update(item, field, new_value)
+      display_item(updated_item)
     end
 
     desc 'delete (d) [id]', 'delete a task'
+    # Deletes a specific tracking item by its ID after confirming with the user.
+    #
+    # @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.
+    #
+    # @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}")`.
     def delete(id)
       item = @db.find_item(id)
       return puts "No tracked time found for id: #{id}" unless item
@@ -116,6 +206,17 @@ module Timet
     end
 
     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.
+    #
+    # @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 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
@@ -123,18 +224,33 @@ module Timet
       delete_item_and_print_message(id, "Canceled active time tracking #{id}")
     end
 
+    # Determines whether the application should exit when a command fails.
+    #
+    # @return [Boolean] Returns `true`, indicating that the application should exit when a command fails.
+    #
+    # @example Check if the application should exit on failure
+    #   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.
     def self.exit_on_failure?
       true
     end
 
     private
 
-    def insert_item_if_valid(start_time, tag, notes)
-      return unless VALID_STATUSES_FOR_INSERTION.include?(@db.last_item_status)
-
-      @db.insert_item(start_time, tag, notes)
-    end
-
+    # Deletes a tracking item from the database by its ID and prints a confirmation message.
+    #
+    # @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.
+    #
+    # @example Delete a tracking item with ID 1 and print a confirmation message
+    #   delete_item_and_print_message(1, 'Deleted item 1')
+    #
+    # @note The method deletes the tracking item from the database using `@db.delete_item(id)`.
+    # @note After deleting the item, the method prints the provided message using `puts message`.
     def delete_item_and_print_message(id, message)
       @db.delete_item(id)
       puts message

data/lib/timet/application_helper.rb

@@ -3,21 +3,64 @@
 module Timet
   # Provides helper methods for the Timet application.
   module ApplicationHelper
+    # Displays the details of a tracking item.
+    #
+    # @param item [Hash] The tracking item to be displayed.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as displaying the item details.
+    #
+    # @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.
     def display_item(item)
       TimeReport.new(@db).show_row(item)
     end
 
+    # Prompts the user to enter a new value for a specific field of a tracking item.
+    #
+    # @param item [Hash] The tracking item to be edited.
+    # @param field [String] The field to be updated.
+    #
+    # @return [String] The new value entered by the user.
+    #
+    # @example Prompt for a new value for the 'notes' field
+    #   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.
     def prompt_for_new_value(item, field)
       current_value = field_value(item, field)
       prompt = TTY::Prompt.new(active_color: :green)
       prompt.ask("Update #{field} (#{current_value}):")
     end
 
+    # Prompts the user to select a field to edit from a list of available fields.
+    #
+    # @return [String] The selected field in lowercase.
+    #
+    # @example Prompt for a field to edit
+    #   select_field_to_edit
+    #
+    # @note The method uses `TTY::Prompt.new` to display a list of available fields for the user to select from.
+    # @note The method returns the selected field in lowercase.
     def select_field_to_edit
       prompt = TTY::Prompt.new(active_color: :green)
       prompt.select('Edit Field?', Timet::Application::FIELD_INDEX.keys.map(&:capitalize), active_color: :cyan).downcase
     end
 
+    # Retrieves the value of a specific field from a tracking item.
+    #
+    # @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.
+    #
+    # @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`.
     def field_value(item, field)
       index = Timet::Application::FIELD_INDEX[field]
       value = item[index]