checkoff 0.40.0 → 0.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42f156ed0a4b85a8fa1b0887a74c3df016d8245293c547ea6b2ed49be7254b18
-  data.tar.gz: 55e6d2c6c560e4c74c18c8db95f079a36637912973e849154f1f2e2bcb724f97
+  metadata.gz: ca8318553efc488d88a70b394e290ec8030f532ac9b3d4fa4fc67eb60849270a
+  data.tar.gz: cd86cc76ca2f74bed8e35212da234f5cbcad358db6a08d181f702fda149e785a
 SHA512:
-  metadata.gz: 8e200395f12114df856c15c030dcbf4d2a8a7a77333cd431881352975655fa7d6a559626dafb15d9f93c9fbcec47e6c1d1be5afc6f7ee6e5d816d315b4566d20
-  data.tar.gz: 6ce670c2ce1e0b783ca3d044b1e957004dc460cc0b207cda9f7ce12898021c32c94efa44bd4e1a652f76f2986c3a4d9873afbe1fe9e3eeec32df8ab4b9e40072
+  metadata.gz: ecde71759c34fe1cee589084e7c06577726af223cc207f3cb4236f02d3d4fba75662bf622d69de7cabc7f22acb6f041cd8ddfeb142f60aba07051b35a3ac9e00
+  data.tar.gz: bb87fb6a83333fc0efffcd4ce5a37da55689bd617642a15dbbb4b4a1c94cb8511aa9a2e9d11e4fc16fc6ec6631d8191976e125156a1241b8f27367fb0afd4d27

data/Gemfile.lock

@@ -12,7 +12,7 @@ GIT
 PATH
   remote: .
   specs:
-    checkoff (0.40.0)
+    checkoff (0.41.0)
       activesupport
       asana (> 0.10.0)
       cache_method

data/lib/checkoff/internal/config_loader.rb

@@ -39,6 +39,7 @@ module Checkoff
     # Load configuration file
     class ConfigLoader
       class << self
+        # @return EnvFallbackConfigLoader
         def load(sym)
           yaml_result = load_yaml_file(sym)
           EnvFallbackConfigLoader.new(yaml_result, sym, yaml_filename(sym))

data/lib/checkoff/internal/task_selector_evaluator.rb

@@ -3,28 +3,47 @@
 module Checkoff
   # Base class to evaluate a task selector function given fully evaluated arguments
   class FunctionEvaluator
+    # @param task_selector [Array<(Symbol, Array)>]
+    # @param tasks [Checkoff::Tasks]
     def initialize(task_selector:,
                    tasks:)
       @task_selector = task_selector
       @tasks = tasks
     end
 
+    # @sg-ignore
+    # @param _index [Integer]
     def evaluate_arg?(_index)
       true
     end
 
+    # @sg-ignore
+    # @return [Boolean]
+    def matches?
+      raise 'Override me!'
+    end
+
     private
 
+    # @param object [Object]
+    # @param fn_name [Symbol]
     def fn?(object, fn_name)
       object.is_a?(Array) && !object.empty? && [fn_name, fn_name.to_s].include?(object[0])
     end
 
+    # @sg-ignore
+    # @param task [Asana::Resources::Task]
+    # @param custom_field_gid [String]
+    # @return [Hash]
     def pull_custom_field_or_raise(task, custom_field_gid)
+      # @type [Array<Hash>]
       custom_fields = task.custom_fields
       if custom_fields.nil?
         raise "Could not find custom_fields under task (was 'custom_fields' included in 'extra_fields'?)"
       end
 
+      # @sg-ignore
+      # @type [Hash, nil]
       matched_custom_field = custom_fields.find { |data| data.fetch('gid') == custom_field_gid }
       if matched_custom_field.nil?
         raise "Could not find custom field with gid #{custom_field_gid} " \
@@ -34,8 +53,12 @@ module Checkoff
       matched_custom_field
     end
 
+    # @return [Array<(Symbol, Array)>]
     attr_reader :task_selector
 
+    # @sg-ignore
+    # @param custom_field [Hash]
+    # @return [Array<String>]
     def pull_enum_values(custom_field)
       resource_subtype = custom_field.fetch('resource_subtype')
       case resource_subtype
@@ -48,6 +71,9 @@ module Checkoff
       end
     end
 
+    # @param custom_field [Hash]
+    # @param enum_value [Object, nil]
+    # @return [Array<String>]
     def find_gids(custom_field, enum_value)
       if enum_value.nil?
         []
@@ -58,12 +84,42 @@ module Checkoff
       end
     end
 
+    # @param task [Asana::Resources::Task]
+    # @param custom_field_gid [String]
+    # @return [Array<String>]
     def pull_custom_field_values_gids(task, custom_field_gid)
       custom_field = pull_custom_field_or_raise(task, custom_field_gid)
       pull_enum_values(custom_field).flat_map do |enum_value|
         find_gids(custom_field, enum_value)
       end
     end
+
+    # @sg-ignore
+    # @param task [Asana::Resources::Task]
+    # @param custom_field_name [String]
+    # @return [Hash, nil]
+    def pull_custom_field_by_name(task, custom_field_name)
+      custom_fields = task.custom_fields
+      if custom_fields.nil?
+        raise "custom fields not found on task - did you add 'custom_field' in your extra_fields argument?"
+      end
+
+      # @sg-ignore
+      # @type [Hash, nil]
+      custom_fields.find { |field| field.fetch('name') == custom_field_name }
+    end
+
+    # @param task [Asana::Resources::Task]
+    # @param custom_field_name [String]
+    # @return [Hash]
+    def pull_custom_field_by_name_or_raise(task, custom_field_name)
+      custom_field = pull_custom_field_by_name(task, custom_field_name)
+      if custom_field.nil?
+        raise "Could not find custom field with name #{custom_field_name} " \
+              "in task #{task.gid} with custom fields #{task.custom_fields}"
+      end
+      custom_field
+    end
   end
 
   # :and function
@@ -72,6 +128,10 @@ module Checkoff
       fn?(task_selector, :and)
     end
 
+    # @param _task [Asana::Resources::Task]
+    # @param lhs [Object]
+    # @param rhs [Object]
+    # @return [Object]
     def evaluate(_task, lhs, rhs)
       lhs && rhs
     end
@@ -83,6 +143,9 @@ module Checkoff
       fn?(task_selector, :not)
     end
 
+    # @param _task [Asana::Resources::Task]
+    # @param subvalue [Object]
+    # @return [Boolean]
     def evaluate(_task, subvalue)
       !subvalue
     end
@@ -94,6 +157,9 @@ module Checkoff
       fn?(task_selector, :nil?)
     end
 
+    # @param _task [Asana::Resources::Task]
+    # @param subvalue [Object]
+    # @return [Boolean]
     def evaluate(_task, subvalue)
       subvalue.nil?
     end
@@ -105,10 +171,15 @@ module Checkoff
       fn?(task_selector, :tag)
     end
 
+    # @param _index [Integer]
     def evaluate_arg?(_index)
       false
     end
 
+    # @sg-ignore
+    # @param task [Asana::Resources::Task]
+    # @param tag_name [String]
+    # @return [Boolean]
     def evaluate(task, tag_name)
       task.tags.map(&:name).include? tag_name
     end
@@ -120,6 +191,8 @@ module Checkoff
       fn?(task_selector, :due)
     end
 
+    # @param task [Asana::Resources::Task]
+    # @return [Boolean]
     def evaluate(task)
       @tasks.task_ready?(task)
     end
@@ -131,6 +204,9 @@ module Checkoff
       fn?(task_selector, :due_date_set)
     end
 
+    # @sg-ignore
+    # @param task [Asana::Resources::Task]
+    # @return [Boolean]
     def evaluate(task)
       !task.due_at.nil? || !task.due_on.nil?
     end
@@ -142,17 +218,16 @@ module Checkoff
       fn?(task_selector, :custom_field_value)
     end
 
+    # @param _index [Integer]
     def evaluate_arg?(_index)
       false
     end
 
+    # @param task [Asana::Resources::Task]
+    # @param custom_field_name [String]
+    # @return [String, nil]
     def evaluate(task, custom_field_name)
-      custom_fields = task.custom_fields
-      if custom_fields.nil?
-        raise "custom fields not found on task - did you add 'custom_field' in your extra_fields argument?"
-      end
-
-      custom_field = custom_fields.find { |field| field.fetch('name') == custom_field_name }
+      custom_field = pull_custom_field_by_name(task, custom_field_name)
       return nil if custom_field.nil?
 
       custom_field['display_value']
@@ -169,6 +244,10 @@ module Checkoff
       false
     end
 
+    # @sg-ignore
+    # @param task [Asana::Resources::Task]
+    # @param custom_field_gid [String]
+    # @return [String, nil]
     def evaluate(task, custom_field_gid)
       custom_field = pull_custom_field_or_raise(task, custom_field_gid)
       custom_field['display_value']
@@ -185,6 +264,10 @@ module Checkoff
       false
     end
 
+    # @param task [Asana::Resources::Task]
+    # @param custom_field_gid [String]
+    # @param custom_field_values_gids [Array<String>]
+    # @return [Boolean]
     def evaluate(task, custom_field_gid, custom_field_values_gids)
       actual_custom_field_values_gids = pull_custom_field_values_gids(task, custom_field_gid)
 
@@ -204,6 +287,10 @@ module Checkoff
       false
     end
 
+    # @param task [Asana::Resources::Task]
+    # @param custom_field_gid [String]
+    # @param custom_field_values_gids [Array<String>]
+    # @return [Boolean]
     def evaluate(task, custom_field_gid, custom_field_values_gids)
       actual_custom_field_values_gids = pull_custom_field_values_gids(task, custom_field_gid)
 
@@ -213,8 +300,34 @@ module Checkoff
     end
   end
 
+  # :custom_field_less_than_n_days_from_now function
+  class CustomFieldLessThanNDaysFromNowFunctionEvaluator < FunctionEvaluator
+    def matches?
+      fn?(task_selector, :custom_field_less_than_n_days_from_now)
+    end
+
+    def evaluate_arg?(_index)
+      false
+    end
+
+    # @param task [Asana::Resources::Task]
+    # @param custom_field_name [String]
+    # @param num_days [Integer]
+    # @return [Boolean]
+    def evaluate(task, custom_field_name, num_days)
+      custom_field = pull_custom_field_by_name_or_raise(task, custom_field_name)
+
+      time_str = custom_field.fetch('display_value')
+      time = Time.parse(time_str)
+      n_days_from_now = (Time.now + (num_days * 24 * 60 * 60))
+      time < n_days_from_now
+    end
+  end
+
   # Evaluator task selectors against a task
   class TaskSelectorEvaluator
+    # @param task [Asana::Resources::Task]
+    # @param tasks [Checkoff::Tasks]
     def initialize(task:,
                    tasks: Checkoff::Tasks.new)
       @task = task
@@ -232,12 +345,18 @@ module Checkoff
       AndFunctionEvaluator,
       DuePFunctionEvaluator,
       DueDateSetPFunctionEvaluator,
+      CustomFieldLessThanNDaysFromNowFunctionEvaluator,
     ].freeze
 
+    # @param task_selector [Array]
+    # @return [Boolean, Object, nil]
     def evaluate(task_selector)
-      return true if task_selector == []
+      return true if task_selector.empty?
 
+      # @param evaluator_class [Class<FunctionEvaluator>]
       FUNCTION_EVALUTORS.each do |evaluator_class|
+        # @sg-ignore
+        # @type [FunctionEvaluator]
         evaluator = evaluator_class.new(task_selector: task_selector,
                                         tasks: tasks)
 
@@ -246,11 +365,15 @@ module Checkoff
         return try_this_evaluator(task_selector, evaluator)
       end
 
-      raise "Syntax issue trying to handle #{task_selector}"
+      raise "Syntax issue trying to handle #{task_selector.inspect}"
     end
 
     private
 
+    # @sg-ignore
+    # @param task_selector [Array]
+    # @param evaluator [FunctionEvaluator]
+    # @return [Boolean, Object, nil]
     def try_this_evaluator(task_selector, evaluator)
       evaluated_args = task_selector[1..].map.with_index do |item, index|
         if evaluator.evaluate_arg?(index)
@@ -263,6 +386,11 @@ module Checkoff
       evaluator.evaluate(task, *evaluated_args)
     end
 
-    attr_reader :task, :tasks, :task_selector
+    # @return [Asana::Resources::Task]
+    attr_reader :task
+    # @return [Checkoff::Tasks]
+    attr_reader :tasks
+    # @return [Array<(Symbol, Array)>]
+    attr_reader :task_selector
   end
 end

data/lib/checkoff/task_searches.rb

@@ -19,12 +19,9 @@ module Checkoff
   # Run task searches against the Asana API
   class TaskSearches
     MINUTE = 60
-    # @sg-ignore
     HOUR = MINUTE * 60
     DAY = 24 * HOUR
-    # @sg-ignore
     REALLY_LONG_CACHE_TIME = HOUR * 1
-    # @sg-ignore
     LONG_CACHE_TIME = MINUTE * 15
     SHORT_CACHE_TIME = MINUTE
 
@@ -62,7 +59,6 @@ module Checkoff
                                                     client: client)
       tasks.select { |task| task_selectors.filter_via_task_selector(task, task_selector) }
     end
-    # @sg-ignore
     cache_method :task_search, LONG_CACHE_TIME
 
     private
@@ -81,11 +77,7 @@ module Checkoff
     # :nocov:
     class << self
       def run
-        # @sg-ignore
-        # @type [String]
         workspace_name = ARGV[0] || raise('Please pass workspace name as first argument')
-        # @sg-ignore
-        # @type [String]
         url = ARGV[1] || raise('Please pass task search URL as second argument')
         task_searches = Checkoff::TaskSearches.new
         task_search = task_searches.task_search(workspace_name, url)

data/lib/checkoff/task_selectors.rb

@@ -21,6 +21,10 @@ module Checkoff
     LONG_CACHE_TIME = MINUTE * 15
     SHORT_CACHE_TIME = MINUTE
 
+    # @sg-ignore
+    # @param [Hash] config
+    # @param [Asana::Client] client
+    # @param [Checkoff::Tasks] tasks
     def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    client: Checkoff::Clients.new(config: config).client,
                    tasks: Checkoff::Tasks.new(config: config,
@@ -30,8 +34,8 @@ module Checkoff
     end
 
     # @param [Asana::Resources::Task] task
-    # @param [Hash<Symbol, Object>] task_selector Filter based on
-    #        description.  Examples: {tag: 'foo'} {:not {tag: 'foo'} (:tag 'foo')
+    # @param [Array<(Symbol, Array)>] task_selector Filter based on
+    #        task details.  Examples: [:tag, 'foo'] [:not, [:tag, 'foo']] [:tag, 'foo']
     # @return [Boolean]
     def filter_via_task_selector(task, task_selector)
       evaluator = TaskSelectorEvaluator.new(task: task, tasks: tasks)
@@ -40,16 +44,19 @@ module Checkoff
 
     private
 
+    # @return [Checkoff::Tasks]
     attr_reader :tasks
 
     # bundle exec ./task_selectors.rb
     # :nocov:
     class << self
+      # @sg-ignore
       # @return [String]
       def project_name
         ARGV[1] || raise('Please pass project name to pull tasks from as first argument')
       end
 
+      # @sg-ignore
       # @return [String]
       def workspace_name
         ARGV[0] || raise('Please pass workspace name as first argument')
@@ -61,6 +68,7 @@ module Checkoff
         JSON.parse(task_selector_json)
       end
 
+      # @return [void]
       def run
         require 'checkoff/projects'
 

data/lib/checkoff/version.rb

@@ -3,5 +3,5 @@
 # Command-line and gem client for Asana (unofficial)
 module Checkoff
   # Version of library
-  VERSION = '0.40.0'
+  VERSION = '0.41.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: checkoff
 version: !ruby/object:Gem::Version
-  version: 0.40.0
+  version: 0.41.0
 platform: ruby
 authors:
 - Vince Broz
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-06-18 00:00:00.000000000 Z
+date: 2023-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport