checkoff 0.36.1 → 0.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1695c4a845c22ee1bbdb6ffb62eb1c78b119867b06c1a004e713eab663f315f6
-  data.tar.gz: f55d3aeaf99ff74dba23349ff6b8bd388c92236236fcbc51f34416812b1c5a83
+  metadata.gz: fb28394467995eb9df10b9fa896614dca20ef97b0759c2945bb3baaf98ba0d56
+  data.tar.gz: 3b565699736d8956d83a94e8c93d910ecfac4f7f65280e27303d0da8dd3fd6ff
 SHA512:
-  metadata.gz: 6b24d4ebc9fb9d6f82eaf53ea5fa7cbc949dcf9d0df84e93e547c09d364bfe291c90e86222cd092eea0b68a3acae3943cde8225980ce9c4ae5eafd4719685605
-  data.tar.gz: b49d2c7e82b74159b0eec2105d27f91be60e58ecabc4c5074ca14d09f52381baec100d96a88f02eacaefb26447fab43e5df108c848d28c4598aab5f9b23320d3
+  metadata.gz: 3cfeaa16ebe32cda3959dfce64b72382e743d5dcf40a2d1771c2b2d725594f8d505f094139163bca7e6059908b02d5811260c75b7670126a1bcdf22fb306c9f6
+  data.tar.gz: 9066df52dadb002a5b8bd34a7a1fc852d1e45b4543202e21995dee9e491703357ba305b612c5772d5c9c0153e5c7245c9304988e0f5751b608bfbe03e420d214

data/Gemfile.lock

@@ -12,7 +12,7 @@ GIT
 PATH
   remote: .
   specs:
-    checkoff (0.36.1)
+    checkoff (0.38.0)
       activesupport
       asana (> 0.10.0)
       cache_method
@@ -22,7 +22,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.0.4.3)
+    activesupport (7.0.5)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -145,19 +145,6 @@ GEM
     reverse_markdown (2.1.1)
       nokogiri
     rexml (3.2.5)
-    rspec (3.11.0)
-      rspec-core (~> 3.11.0)
-      rspec-expectations (~> 3.11.0)
-      rspec-mocks (~> 3.11.0)
-    rspec-core (3.11.0)
-      rspec-support (~> 3.11.0)
-    rspec-expectations (3.11.1)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-mocks (3.11.1)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-support (3.11.1)
     rubocop (1.36.0)
       json (~> 2.3)
       parallel (~> 1.10)
@@ -239,7 +226,6 @@ DEPENDENCIES
   punchlist
   rake (~> 13.0)
   rbs (> 3.0.3)
-  rspec (>= 3.4)
   rubocop (~> 1.36, < 1.44)
   rubocop-minitest
   rubocop-rake

data/checkoff.gemspec

@@ -46,7 +46,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 13.0'
   # ensure recent definitions
   spec.add_development_dependency 'rbs', ['>3.0.3']
-  spec.add_development_dependency 'rspec', '>=3.4'
   # I haven't adapted things to Gemspec/DevelopmentDependencies yet,
   # which arrives in 1.44
   spec.add_development_dependency 'rubocop', ['~> 1.36', '<1.44']

data/config/definitions.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+#
+# @!parse
+#   class Time
+#     class << self
+#       # @param date [String]
+#       # @return [Time]
+#       def parse(date); end
+#     end
+#   end
+#   module Asana
+#     class Client
+#       # @return [Asana::ProxiedResourceClasses::Task]
+#       def tasks; end
+#       # @return [Asana::ProxiedResourceClasses::Workspace]
+#       def workspaces; end
+#     end
+#     module Resources
+#       class Task
+#         # @return [String, nil]
+#         def html_notes; end
+#         class << self
+#           # @return [Asana::Resources::Task]
+#           def create(client, assignee:, workspace:, name:); end
+#         end
+#       end
+#     end
+#     module Resources
+#       class Workspace
+#         # @return [String, nil]
+#         def html_notes; end
+#         class << self
+#           # @return [Asana::Resources::Workspace]
+#           def find_by_id(client, id, options: {}); end
+#         end
+#       end
+#     end
+#     module ProxiedResourceClasses
+#       class Task
+#         # Returns the complete task record for a single task.
+#         #
+#         # @param id [String] The task to get.
+#         # @param options [Hash] the request I/O options.
+#         # @return [Asana::Resources::Task]
+#         def find_by_id(id, options: {}); end
+#       end
+#       class Workspace
+#         # @return [Array<Asana::Resources::Workspace>]
+#         def find_all; end
+#       end
+#     end
+#   end

data/lib/checkoff/internal/search_url/parser.rb

@@ -2,6 +2,8 @@
 
 # frozen_string_literal: true
 
+require 'cgi'
+require 'uri'
 require_relative 'simple_param_converter'
 require_relative 'custom_field_param_converter'
 
@@ -17,7 +19,9 @@ module Checkoff
 
         def convert_params(url)
           url_params = CGI.parse(URI.parse(url).query)
+          # @sg-ignore
           custom_field_params, simple_url_params = partition_url_params(url_params)
+          # @sg-ignore
           custom_field_args, task_selector = convert_custom_field_params(custom_field_params)
           simple_url_args = convert_simple_params(simple_url_params)
           [custom_field_args.merge(simple_url_args), task_selector]
@@ -33,6 +37,8 @@ module Checkoff
           CustomFieldParamConverter.new(custom_field_params: custom_field_params).convert
         end
 
+        # @param url_params [Hash<String, String>]
+        # @return [Array(Hash<String, String>, Hash<String, String>)]
         def partition_url_params(url_params)
           url_params.to_a.partition do |key, _values|
             key.start_with? 'custom_field_'

data/lib/checkoff/internal/search_url/simple_param_converter.rb

@@ -11,6 +11,8 @@ module Checkoff
       module SimpleParam
         # base class for handling different types of search url params
         class SimpleParam
+          # @param key [String] the name of the search url param
+          # @param values [Array<String>] the values of the search url param
           def initialize(key:, values:)
             @key = key
             @values = values
@@ -18,10 +20,13 @@ module Checkoff
 
           private
 
+          # @sg-ignore
+          # @return [String] the single value of the search url param
           def single_value
             @single_value ||= begin
               raise "Teach me how to handle #{key} = #{values}" if values.length != 1
 
+              # @type [String]
               values.fetch(0)
             end
           end
@@ -34,6 +39,7 @@ module Checkoff
           #   123~456 means "abc" and "def" projects
           def parse_projects_and_sections(projects, sections)
             single_value.split('~').each do |project_section_pair|
+              # @sg-ignore
               project, section = project_section_pair.split('_column_')
               if section.nil?
                 projects << project
@@ -106,15 +112,32 @@ module Checkoff
             ['tags.any', tag_ids.join(',')]
           end
         end
+
+        # Handle 'sort' search url param
+        class Sort < SimpleParam
+          def convert
+            # https://developers.asana.com/reference/searchtasksforworkspace
+            conversion = {
+              'last_modified' => 'modified_at',
+              'due_date' => 'due_date',
+              'creation_time' => 'created_at',
+              'completion_time' => 'completed_at',
+              'likes' => 'likes',
+            }
+            ['sort_by', conversion.fetch(single_value)]
+          end
+        end
       end
 
       # Convert simple parameters - ones where the param name itself
       # doesn't encode any parameters'
       class SimpleParamConverter
+        # @param simple_url_params [Hash<String, Array<String>>] the simple params
         def initialize(simple_url_params:)
           @simple_url_params = simple_url_params
         end
 
+        # @return [Hash<String, String>] the converted params
         def convert
           simple_url_params.to_a.flat_map do |key, values|
             convert_arg(key, values).each_slice(2).to_a
@@ -123,6 +146,7 @@ module Checkoff
 
         private
 
+        # @type [Hash<String, Class<SimpleParam::SimpleParam>>] the mapping from param name to class
         ARGS = {
           'any_projects.ids' => SimpleParam::AnyProjectsIds,
           'not_projects.ids' => SimpleParam::NotProjectsIds,
@@ -130,12 +154,21 @@ module Checkoff
           'not_tags.ids' => SimpleParam::NotTagsIds,
           'any_tags.ids' => SimpleParam::AnyTagsIds,
           'subtask' => SimpleParam::Subtask,
+          'sort' => SimpleParam::Sort,
         }.freeze
 
         # https://developers.asana.com/docs/search-tasks-in-a-workspace
+        # @sg-ignore
+        # @param key [String] the name of the search url param
+        # @param values [Array<String>] the values of the search url param
+        # @return [Hash<String, String>] the converted params
         def convert_arg(key, values)
+          # @type [Class<SimpleParam::SimpleParam>]
           clazz = ARGS.fetch(key)
-          clazz.new(key: key, values: values).convert
+          # @type [SimpleParam::SimpleParam]
+          obj = clazz.new(key: key, values: values)
+          # @sg-ignore
+          obj.convert
         end
 
         attr_reader :simple_url_params

data/lib/checkoff/projects.rb

@@ -17,12 +17,19 @@ module Checkoff
   # Work with projects in Asana
   class Projects
     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
 
+    # @!parse
+    #   extend CacheMethod::ClassMethods
+
+    # @param client [Asana::Client]
     def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    client: Checkoff::Clients.new(config: config).client,
                    workspaces: Checkoff::Workspaces.new(config: config,
@@ -33,7 +40,7 @@ module Checkoff
     end
 
     # Default options used in Asana API to pull taskso
-    # @return [Hash]
+    # @return [Hash<Symbol, Object>]
     def task_options
       {
         per_page: 100,
@@ -45,6 +52,9 @@ module Checkoff
     end
 
     # pulls an Asana API project class given a name
+    # @param [String] workspace_name
+    # @param [String] project_name
+    # @return [Asana::Resources::Project, nil]
     def project(workspace_name, project_name)
       if project_name.is_a?(Symbol) && project_name.to_s.start_with?('my_tasks')
         my_tasks(workspace_name)
@@ -57,21 +67,30 @@ module Checkoff
     end
     cache_method :project, LONG_CACHE_TIME
 
-    # @return [Asana::Project]
+    # @param workspace_name [String]
+    # @param project_name [String]
+    # @return [Asana::Resources::Project]
     def project_or_raise(workspace_name, project_name)
-      project = project(workspace_name, project_name)
-      raise "Could not find project #{project_name} under workspace #{workspace_name}." if project.nil?
+      p = project(workspace_name, project_name)
+      raise "Could not find project #{project_name} under workspace #{workspace_name}." if p.nil?
 
-      project
+      p
     end
     cache_method :project_or_raise, LONG_CACHE_TIME
 
     # find uncompleted tasks in a list
+    # @param [Array<Asana::Resources::Task>] tasks
+    # @return [Array<Asana::Resources::Task>]
     def active_tasks(tasks)
       tasks.select { |task| task.completed_at.nil? }
     end
 
     # pull task objects from a named project
+    # @sg-ignore
+    # @param [Asana::Resources::Project] project
+    # @param [Boolean] only_uncompleted
+    # @param [Array<String>] extra_fields
+    # @return [Array<Asana::Resources::Task>]
     def tasks_from_project(project, only_uncompleted: true, extra_fields: [])
       options = task_options
       options[:completed_since] = '9999-12-01' if only_uncompleted
@@ -85,11 +104,15 @@ module Checkoff
 
     attr_reader :client
 
+    # @sg-ignore
     def projects
       client.projects
     end
     cache_method :projects, LONG_CACHE_TIME
 
+    # @sg-ignore
+    # @param [String] workspace_name
+    # @return [Array<Asana::Resources::Project>]
     def projects_by_workspace_name(workspace_name)
       workspace = @workspaces.workspace_or_raise(workspace_name)
       raise "Could not find workspace named #{workspace_name}" unless workspace
@@ -97,8 +120,13 @@ module Checkoff
       projects.find_by_workspace(workspace: workspace.gid)
     end
 
+    # @sg-ignore
+    # @param [String] workspace_name
+    # @return [Asana::Resources::Project]
     def my_tasks(workspace_name)
       workspace = @workspaces.workspace_or_raise(workspace_name)
+      # @sg-ignore
+      # @type [Asana::Resources::UserTaskList]
       result = client.user_task_lists.get_user_task_list_for_user(user_gid: 'me',
                                                                   workspace: workspace.gid)
       gid = result.gid

data/lib/checkoff/task_searches.rb

@@ -19,9 +19,12 @@ 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
 
@@ -59,11 +62,15 @@ 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
 
+    # @param [Array<String>] extra_fields
+    # @return [Hash<Symbol, Object>]
     def calculate_api_options(extra_fields)
+      # @type [Hash<Symbol, Object>]
       options = projects.task_options[:options]
       options[:fields] += ['custom_fields']
       options[:fields] += extra_fields
@@ -74,7 +81,11 @@ 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/tasks.rb

@@ -3,21 +3,30 @@
 # frozen_string_literal: true
 
 require_relative 'sections'
+require_relative 'workspaces'
 require 'asana'
 
 module Checkoff
   # Pull tasks from Asana
   class Tasks
     MINUTE = 60
+    # @sg-ignore
     HOUR = MINUTE * 60
     DAY = 24 * HOUR
     REALLY_LONG_CACHE_TIME = HOUR
+    # @sg-ignore
     LONG_CACHE_TIME = MINUTE * 15
+    # @sg-ignore
     SHORT_CACHE_TIME = MINUTE * 5
 
+    # @param client [Asana::Client]
+    # @param workspaces [Checkoff::Workspaces]
+    # @param time_class [Class<Time>]
     # @param sections [Checkoff::Sections]
     def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    client: Checkoff::Clients.new(config: config).client,
+                   workspaces: Checkoff::Workspaces.new(config: config,
+                                                        client: client),
                    sections: Checkoff::Sections.new(config: config,
                                                     client: client),
                    time_class: Time,
@@ -27,6 +36,7 @@ module Checkoff
       @time_class = time_class
       @asana_task = asana_task
       @client = client
+      @workspaces = workspaces
     end
 
     def task_ready?(task)
@@ -53,9 +63,22 @@ module Checkoff
       tasks.find { |task| task.name == task_name }
     end
 
+    # Pull a specific task by name
+    # @return [Asana::Resources::Task, nil]
+    def task_by_gid(task_gid,
+                    only_uncompleted: true,
+                    extra_fields: [])
+      options = projects.task_options
+      options[:options][:fields] += extra_fields
+      options[:completed_since] = '9999-12-01' if only_uncompleted
+      client.tasks.find_by_id(task_gid, options: options)
+    end
+
+    # @param workspace_gid [String]
+    # @param assignee_gid [String]
     # @return [Asana::Resources::Task]
     def add_task(name,
-                 workspace_gid: default_workspace_gid,
+                 workspace_gid: @workspaces.default_workspace_gid,
                  assignee_gid: default_assignee_gid)
       @asana_task.create(client,
                          assignee: assignee_gid,
@@ -93,11 +116,14 @@ module Checkoff
       @projects ||= @sections.projects
     end
 
+    # @sg-ignore
     # @return [String]
     def default_assignee_gid
       @config.fetch(:default_assignee_gid)
     end
 
+    # @param task [Asana::Resources::Task]
+    # @return [Time, nil]
     def due_time(task)
       return @time_class.parse(task.due_at) if task.due_at
       return @time_class.parse(task.due_on) if task.due_on
@@ -117,6 +143,7 @@ module Checkoff
       # @sg-ignore
       # @type [Array<Asana::Resources::Task>, nil]
       already_fetched_dependencies = task.instance_variable_get(:@dependencies)
+      # @sg-ignore
       return false unless already_fetched_dependencies.nil? || already_fetched_dependencies.size.positive?
 
       task.dependencies.any? do |parent_task_info|

data/lib/checkoff/version.rb

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

data/lib/checkoff/workspaces.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'asana'
 require 'forwardable'
 require 'cache_method'
 require_relative 'internal/config_loader'
@@ -11,12 +12,16 @@ module Checkoff
   # Query different workspaces of Asana projects
   class Workspaces
     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
 
+    # @param client [Asana::Client]
     def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    client: Checkoff::Clients.new(config: config).client,
                    asana_workspace: Asana::Resources::Workspace)
@@ -26,29 +31,36 @@ module Checkoff
     end
 
     # Pulls an Asana workspace object
+    # @param [String] workspace_name
+    # @return [Asana::Resources::Workspace, nil]
     def workspace(workspace_name)
       client.workspaces.find_all.find do |workspace|
         workspace.name == workspace_name
       end
     end
 
+    # @return [Asana::Resources::Workspace]
     def default_workspace
       @asana_workspace.find_by_id(client, default_workspace_gid)
     end
 
+    # @param [String] workspace_name
+    # @return [Asana::Resources::Workspace]
     def workspace_or_raise(workspace_name)
-      workspace = workspace(workspace_name)
-      raise "Could not find workspace #{workspace_name}" if workspace.nil?
+      w = workspace(workspace_name)
+      raise "Could not find workspace #{workspace_name}" if w.nil?
 
-      workspace
+      w
     end
 
-    private
-
-    attr_reader :client
-
+    # @sg-ignore
+    # @return [String]
     def default_workspace_gid
       @config.fetch(:default_workspace_gid)
     end
+
+    private
+
+    attr_reader :client
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: checkoff
 version: !ruby/object:Gem::Version
-  version: 0.36.1
+  version: 0.38.0
 platform: ruby
 authors:
 - Vince Broz
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-05-20 00:00:00.000000000 Z
+date: 2023-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -254,20 +254,6 @@ dependencies:
     - - ">"
       - !ruby/object:Gem::Version
         version: 3.0.3
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '3.4'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '3.4'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -425,6 +411,7 @@ files:
 - bin/solargraph
 - bin/yard
 - checkoff.gemspec
+- config/definitions.rb
 - docs/cookiecutter_input.json
 - docs/example_project.png
 - exe/checkoff