fewald-worklog 0.2.15 → 0.2.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25cba6c16164da66d60c6ea7f00d3f37a32b2e0cb2fdefd8be7ea862346542a5
-  data.tar.gz: c094a3fca2e496c9d70684db1fde141695a8db36d1511c4ab01df7764da33e4a
+  metadata.gz: 226d608638c12cd6ed618d5669d1e675baf2826ec9f7092887cf08b2612bf845
+  data.tar.gz: 897ee2bbd7ee446a2397815632c0738115c7b2ce4e37251ef3197db7cbf1c7fc
 SHA512:
-  metadata.gz: 10fdaa8f8ca7ee544d5476c22bac3652eda53548a9d439178cc7b4ab8c7fdd904f8831f779146985d2224f6d6395e310f6d692d45e7fed82c5434a989152d527
-  data.tar.gz: c6a472717293fbe7ba7dc6a79175c5a9b305c8a14e5039e4e260594b388e90355899a9cf10cc4e95198a1a5621dc9a6542292bd2afdcaa16521da4b6803dbf4c
+  metadata.gz: c313a4c546a9aa10ca55c718fda09a9ec3bedd3e16bea9beaea95cfb0153ac1b2ac3be1f8d06f5a5baa60e33d451bfbb270c2f6ddbc31a381462da6e549dd8db
+  data.tar.gz: bede43615c16b5c457e953c0f30a902cfaeaa4d55dc7ddcc9d00bdfe6f27e9b40676ee94a88d7c2d89d34b6321bd8e0284fd8233c4144c4ee1864a91505e7091

data/.version

@@ -1 +1 @@
-0.2.15
+0.2.18

data/lib/cli.rb

@@ -92,6 +92,7 @@ class WorklogCLI < Thor
   EOF
   option :epics_only, type: :boolean, default: false, desc: 'Show only entries that are marked as epic'
   option :tags, type: :array, default: [], desc: 'Filter entries by tags. Tags are treated as an OR condition.'
+  option :project, type: :string, desc: 'Filter entries by project key.'
   def show
     worklog = Worklog::Worklog.new
     worklog.show(options)

data/lib/printer.rb

@@ -15,7 +15,15 @@ class Printer
   # Prints a whole day of work log entries.
   # If date_inline is true, the date is printed inline with the time.
   # If epics_only is true, only epic entries are printed.
-  def print_day(daily_log, date_inline = false, epics_only = false)
+  # @param daily_log [DailyLog] The daily log containing entries.
+  # @param date_inline [Boolean] If true, the date is printed inline with the time.
+  # @param epics_only [Boolean] If true, only epic entries are printed.
+  # @param filter [Hash] A hash of filters to apply to the entries.
+  # @return [void]
+  # @example
+  #   printer.print_day(daily_log, date_inline: true, epics_only: false, project: 'xyz')
+  #   printer.print_day(daily_log, date_inline: false, epics_only: true)
+  def print_day(daily_log, date_inline = false, epics_only = false, filter = {})
     daily_log.date = Date.strptime(daily_log.date, '%Y-%m-%d') unless daily_log.date.respond_to?(:strftime)
 
     date_string = daily_log.date.strftime('%a, %B %-d, %Y')
@@ -24,6 +32,8 @@ class Printer
     daily_log.entries.each do |entry|
       next if epics_only && !entry.epic?
 
+      next unless filter.compact.all? { |k, v| entry.send(k) == v }
+
       print_entry(daily_log, entry, date_inline)
     end
   end

data/lib/project.rb

@@ -3,8 +3,24 @@
 module Worklog
   # Represents a project. A project is a longer running task or initiative.
   # Single log entries can be associated with a project.
+  # @!attribute [rw] key
+  #   @return [String] Unique identifier for the project, used in log entries.
+  # @!attribute [rw] name
+  #   @return [String] The human-readable name of the project.
+  # @!attribute [rw] description
+  #   @return [String, nil] A description of the project, can be nil
+  # @!attribute [rw] start_date
+  #   @return [Date, nil] The start date of the project, can be nil
+  # @!attribute [rw] end_date
+  #   @return [Date, nil] The end date of the project, can be nil
+  # @!attribute [rw] status
+  #   @return [String, nil] The status of the project, can be nil
+  #   Possible values: 'active', 'completed', 'archived', etc.
+  #   Indicates the current state of the project.
+  # @!attribute [rw] last_activity
+  #  @return [Date, nil] The last activity date or nil if not set.
   class Project
-    attr_accessor :key, :name, :description, :start_date, :end_date, :status
+    attr_accessor :key, :name, :description, :start_date, :end_date, :status, :last_activity
 
     # Creates a new Project instance from a hash of attributes.
     # @param hash [Hash] A hash containing project attributes

data/lib/project_storage.rb

@@ -10,6 +10,8 @@ module Worklog
 
   # ProjectStorage is responsible for loading and managing project data.
   # It provides methods to load projects from a YAML file and check if a project exists.
+  # @!attribute [w] projects
+  #  @return [Hash<String, Project>] A hash of projects keyed by their project keys.
   #
   # @see Project
   # @see Configuration
@@ -17,6 +19,11 @@ module Worklog
   class ProjectStorage
     attr_writer :projects
 
+    # The name of the YAML file where projects are stored.
+    FILE_NAME = 'projects.yaml'
+
+    # The template for the projects YAML file.
+    # This template is used to create a new projects file if it does not exist.
     PROJECT_TEMPLATE = <<~YAML
       # Each project is defined by the following attributes:
       # - key: <project_key>
@@ -44,7 +51,7 @@ module Worklog
     def load_projects
       create_template unless file_exist?
 
-      file_path = File.join(@configuration.storage_path, 'projects.yml')
+      file_path = File.join(@configuration.storage_path, FILE_NAME)
       projects = {}
       YAML.load_file(file_path, permitted_classes: [Date])&.each do |project_hash|
         project = Project.from_hash(project_hash)
@@ -54,12 +61,14 @@ module Worklog
       projects
     end
 
-    # Check if a project with a given handle exists.
-    # @param handle [String] The handle of the project to check.
+    # Check if a project with a given key exists.
+    # @param key [String] The key of the project to check.
     # @return [Boolean] Returns true if the project exists, false otherwise.
-    def exist?(handle)
+    # @note This method loads the projects from disk if they are not already loaded.
+    # @see load_projects
+    def exist?(key)
       projects = load_projects
-      projects.key?(handle)
+      projects.key?(key)
     end
 
     private
@@ -67,12 +76,20 @@ module Worklog
     # Check whether projects.yaml exists in the project_dir
     # @return [Boolean] Returns true if the project YAML file exists, false otherwise
     def file_exist?
-      file_path = File.join(@configuration.storage_path, 'projects.yml')
+      file_path = File.join(@configuration.storage_path, FILE_NAME)
       File.exist?(file_path)
     end
 
+    # Creates a template for the projects YAML file if it does not exist.
+    # This method writes a predefined template to the projects.yml file.
+    # @return [void]
+    # @note This method will overwrite any existing projects.yml file.
+    # @see PROJECT_TEMPLATE for the structure of the template.
     def create_template
-      File.write(File.join(@configuration.storage_path, 'projects.yml'), PROJECT_TEMPLATE)
+      return unless @configuration.storage_path_exist?
+
+      File.write(File.join(@configuration.storage_path, FILE_NAME), PROJECT_TEMPLATE)
+      nil
     end
   end
 end

data/lib/storage.rb

@@ -93,8 +93,6 @@ class Storage
   # Create file for a new day if it does not exist
   # @param [Date] date The date, used as the file name.
   def create_file_skeleton(date)
-    create_folder
-
     File.write(filepath(date), YAML.dump(DailyLog.new(date:, entries: []))) unless File.exist?(filepath(date))
   end
 
@@ -119,8 +117,6 @@ class Storage
   end
 
   def write_log(file, daily_log)
-    create_folder
-
     WorkLogger.debug "Writing to file #{file}"
 
     File.open(file, 'w') do |f|
@@ -162,8 +158,6 @@ class Storage
   # Write people to the people file
   # @param [Array<Person>] people List of people
   def write_people!(people)
-    create_folder
-
     people_file = File.join(@config.storage_path, 'people.yaml')
     File.open(people_file, 'w') do |f|
       f.puts people.to_yaml
@@ -171,7 +165,10 @@ class Storage
   end
 
   # Create folder if not exists already.
-  def create_folder
+  def create_default_folder
+    # Do nothing if the storage path is not the default path
+    return unless @config.default_storage_path?
+
     Dir.mkdir(@config.storage_path) unless Dir.exist?(@config.storage_path)
   end
 

data/lib/worklog.rb

@@ -22,6 +22,22 @@ module Worklog
   # Main class providing all worklog functionality.
   # This class is the main entry point for the application.
   # It handles command line arguments, configuration, and logging.
+  # @!attribute [r] config
+  #   @return [Configuration] The configuration object containing settings for the application.
+  # @!attribute [r] storage
+  #   @return [Storage] The storage object for managing file operations.
+  #
+  # @see Configuration
+  # @see Storage
+  # @see ProjectStorage
+  #
+  # @example
+  #   worklog = Worklog.new
+  #   worklog.add('Worked on feature X',
+  #                date: '2023-10-01',
+  #                time: '10:00:00',
+  #                tags: ['feature', 'x'],
+  #                ticket: 'TICKET-123')
   class Worklog
     include StringHelper
     attr_reader :config, :storage
@@ -31,6 +47,13 @@ module Worklog
       @storage = Storage.new(@config)
 
       WorkLogger.level = @config.log_level == :debug ? Logger::Severity::DEBUG : Logger::Severity::INFO
+
+      bootstrap
+    end
+
+    # Bootstrap the worklog application.
+    def bootstrap
+      @storage.create_default_folder
     end
 
     # Add new entry to the work log.
@@ -92,6 +115,20 @@ module Worklog
       WorkLogger.info Rainbow("Updated work log for #{options[:date]}").green
     end
 
+    # Show the work log for a specific date range or a single date.
+    #
+    # @param options [Hash] the options hash containing date range or single date.
+    # @option options [Integer] :days the number of days to show from today (default: 1).
+    # @option options [String] :from the start date in 'YYYY-MM-DD' format.
+    # @option options [String] :to the end date in 'YYYY-MM-DD' format.
+    # @option options [String] :date a specific date in 'YYYY-MM-DD' format.
+    # @option options [Boolean] :epics_only whether to show only entries with epics (default: false).
+    # @option options [String] :project the project key to filter entries by project.
+    #
+    # @example
+    #   worklog.show(days: 7)
+    #   worklog.show(from: '2023-10-01', to: '2023-10-31')
+    #   worklog.show(date: '2023-10-01')
     def show(options = {})
       people = @storage.load_people!
       printer = Printer.new(people)
@@ -103,7 +140,7 @@ module Worklog
         printer.no_entries(start_date, end_date)
       else
         entries.each do |entry|
-          printer.print_day(entry, entries.size > 1, options[:epics_only])
+          printer.print_day(entry, entries.size > 1, options[:epics_only], project: options[:project])
         end
       end
     end
@@ -170,8 +207,8 @@ module Worklog
       projects.each_value do |project|
         puts "#{Rainbow(project.name).gold} (#{project.key})"
         puts "  Description: #{project.description}" if project.description
-        puts "  Start date: #{project.start_date}" if project.start_date
-        puts "  End date: #{project.end_date}" if project.end_date
+        puts "  Start date: #{project.start_date.strftime('%b %d, %Y')}" if project.start_date
+        puts "  End date: #{project.end_date.strftime('%b %d, %Y')}" if project.end_date
         puts "  Status: #{project.status}" if project.status
       end
       puts 'No projects found.' if projects.empty?
@@ -326,6 +363,15 @@ module Worklog
       [start_date, end_date]
     end
 
+    # Validate that the project exists in the project storage if a project key is provided.
+    #
+    # @param project_key [String] the project key to validate
+    # @raise [ProjectNotFoundError] if the project does not exist
+    #
+    # @return [void]
+    #
+    # @example
+    #   validate_projects!('P001')
     def validate_projects!(project_key)
       project_storage = ProjectStorage.new(@config)
       begin

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fewald-worklog
 version: !ruby/object:Gem::Version
-  version: 0.2.15
+  version: 0.2.18
 platform: ruby
 authors:
 - Friedrich Ewald