fewald-worklog 0.2.15 → 0.2.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25cba6c16164da66d60c6ea7f00d3f37a32b2e0cb2fdefd8be7ea862346542a5
-  data.tar.gz: c094a3fca2e496c9d70684db1fde141695a8db36d1511c4ab01df7764da33e4a
+  metadata.gz: d406551a4b3ab8ab4845636c440e4d1cc82e5ac6fc0c188328ed8a5b8608c893
+  data.tar.gz: 0170211e2a62fecfd26b58d8d6d8eeff9e0b55412ac9715a79fe67066887430f
 SHA512:
-  metadata.gz: 10fdaa8f8ca7ee544d5476c22bac3652eda53548a9d439178cc7b4ab8c7fdd904f8831f779146985d2224f6d6395e310f6d692d45e7fed82c5434a989152d527
-  data.tar.gz: c6a472717293fbe7ba7dc6a79175c5a9b305c8a14e5039e4e260594b388e90355899a9cf10cc4e95198a1a5621dc9a6542292bd2afdcaa16521da4b6803dbf4c
+  metadata.gz: 222b26f794ceae4b3dfd33be51cd300b07fa0dc594811f30aa6bb66b4d71f79cf985e62663f33fb6305fd0a88d098c9dd91f62e250ef2cbdc416e9673673dc6d
+  data.tar.gz: ec0c33c3041dfe1e3f1d73f2b2b3a3175c7a414beda395f6590af8350a66cdd3d79aaf03143daea1684b0571fff0787bcd5ebd32c7a543f34aadeb78b29ecd75

data/.version

@@ -1 +1 @@
-0.2.15
+0.2.16

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.
@@ -326,6 +349,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.16
 platform: ruby
 authors:
 - Friedrich Ewald