checkoff 0.91.0 → 0.93.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35517b0881d667a3b704f6e4aca139c95e32c8cb3b10c471c80d826fb6ab063c
-  data.tar.gz: 479341030e04f41b32a972502422d159442984dbd4c108213e376e37bd0bb6f3
+  metadata.gz: 49531006387df986e746c99973d425917777230710978cad819951ca8d696d7b
+  data.tar.gz: ef9ea84d3a708b8a47425c77a63f83241f310d2b9b0fd71e01f15ec00d5eb4d7
 SHA512:
-  metadata.gz: d9dfe9cf496894dc305c3f6ac7f424f9dc5ea809220d193549f014ddee0c6563d6791aaa9f8df67957c4f80d73ca8da29fd6e7894ed9c34f182d5c8d8dcf0336
-  data.tar.gz: 522e00146e8ef0d447eb31dce26cbd8ce165bf813af247e9e2aa326ccf3330d07c36dafffaba384ddcb8c2bb6958941a28613208eb0f4062161974a35e5d8d36
+  metadata.gz: 7d5e93cea9b3b00bb6d7622e7aa4aa93229820683118f72414ac60dd7b3fafd36fac60e1a79a16fc6091b4ba051ae3cc818b0e2f8c5a354ae57b4b849b562af0
+  data.tar.gz: e4f24e5b32dfce8459a3c04fc89ba0b831f0d50f61dcc780864f441b1e119f29f774f2b47503ef6653b285b60c58273bb0bca8a80aa7feacea517019ce8139c1

data/GLOSSARY.md

@@ -1,11 +1,11 @@
 # Glossary
 
-* ready/due: See tasks.rb#task_ready?.  Indicates a task is ready for
+* ready: See tasks.rb#task_ready?.  Indicates a task is ready for
   a person to work on it.  This is subtly different than what is used
   by Asana to mark a date as red/green!  A task is ready if it is not
   dependent on an incomplete task and one of these is true:
 
   * start is null and due on is today
-  * start is null and due at is after now
+  * start is null and due at is before now
   * start on is today
-  * start at is after now
+  * start at is before now

data/Gemfile.lock

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

data/config/definitions.rb

@@ -33,6 +33,10 @@
 #       def projects; end
 #       # @return [Asana::ProxiedResourceClasses::UserTaskList]
 #       def user_task_lists; end
+#       # @return [Asana::ProxiedResourceClasses::Portfolio]
+#       def portfolios; end
+#       # @return [Asana::ProxiedResourceClasses::User]
+#       def users; end
 #     end
 #     class Collection < Asana::Resources::Collection; end
 #     module Resources
@@ -160,6 +164,35 @@
 #         def get_user_task_list_for_user(client, user_gid:,
 #             workspace: nil, options: {}); end
 #       end
+#       class Portfolio
+#         # Returns a list of the portfolios in compact representation that are owned
+#         # by the current API user.
+#         #
+#         # @param workspace [Gid] The workspace or organization to filter portfolios on.
+#         # @param owner [String] The user who owns the portfolio. Currently, API users can only get a
+#         # list of portfolios that they themselves own.
+#         #
+#         # @param per_page [Integer] the number of records to fetch per page.
+#         # @param options [Hash] the request I/O options.
+#         #
+#         # @return [Enumerable<Asana::Resources::Portfolio>]
+#         def find_all(workspace: required("workspace"), owner: required("owner"), per_page: 20, options: {}); end
+#         # Returns the complete record for a single portfolio.
+#         #
+#         # @param id [Gid] The portfolio to get.
+#         # @param options [Hash] the request I/O options.
+#
+#         # @return [Asana::Resources::Portfolio,nil]
+#         def find_by_id(client, id, options: {}); end
+#       end
+#       class User
+#         # Returns the full user record for the currently authenticated user.
+#         #
+#         # @param options [Hash] the request I/O options.
+#         #
+#         # @return [Asana::Resources::User]
+#         def me(options: {}); end
+#       end
 #     end
 #   end
 # rubocop:enable Layout/LineLength

data/lib/checkoff/create-entity.sh

@@ -8,6 +8,8 @@ underscored_plural_name="${1:?underscored plural name of entities minus .rb}"
 underscored_singular_name=$(sed -e 's/s$//g' <<< "${underscored_plural_name}")
 kabob_case_plural_name=${underscored_plural_name/_/-}
 class_name="${2:?class name without Checkoff:: prefix}"
+# shellcheck disable=SC2001
+asana_resource_class_name=Asana::Resources::$(sed -e 's/s$//g' <<< "${class_name}")
 
 cat > "${underscored_plural_name}.rb" << EOF
 #!/usr/bin/env ruby
@@ -20,10 +22,13 @@ require_relative 'internal/config_loader'
 require_relative 'workspaces'
 require_relative 'clients'
 
-# https://developers.asana.com/docs/${kabob_case_plural_name}
+# https://developers.asana.com/reference/${kabob_case_plural_name}
 
 module Checkoff
   class ${class_name}
+    # @!parse
+    #   extend CacheMethod::ClassMethods
+
     MINUTE = 60
     HOUR = MINUTE * 60
     DAY = 24 * HOUR
@@ -31,6 +36,10 @@ module Checkoff
     LONG_CACHE_TIME = MINUTE * 15
     SHORT_CACHE_TIME = MINUTE
 
+    # @param config [Hash]
+    # @param workspaces [Checkoff::Workspaces]
+    # @param clients [Checkoff::Clients]
+    # @param client [Asana::Client]
     def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    workspaces: Checkoff::Workspaces.new(config: config),
                    clients: Checkoff::Clients.new(config: config),
@@ -39,31 +48,47 @@ module Checkoff
       @client = client
     end
 
+    # @param workspace_name [String]
+    # @param ${underscored_singular_name}_name [String]
+    #
+    # @return [${asana_resource_class_name}]
     def ${underscored_singular_name}_or_raise(workspace_name, ${underscored_singular_name}_name)
-      ${underscored_singular_name} = ${underscored_singular_name}(workspace_name, ${underscored_singular_name}_name)
-      raise "Could not find ${underscored_singular_name} #{${underscored_singular_name}_name} under workspace #{workspace_name}." if ${underscored_singular_name}.nil?
+      ${underscored_singular_name}_obj = ${underscored_singular_name}(workspace_name, ${underscored_singular_name}_name)
+      raise "Could not find ${underscored_singular_name} #{${underscored_singular_name}_name} under workspace #{workspace_name}." if ${underscored_singular_name}_obj.nil?
 
-      ${underscored_singular_name}
+      ${underscored_singular_name}_obj
     end
     cache_method :${underscored_singular_name}_or_raise, LONG_CACHE_TIME
 
+    # @param workspace_name [String]
+    # @param ${underscored_singular_name}_name [String]
+    #
+    # @return [${asana_resource_class_name},nil]
     def ${underscored_singular_name}(workspace_name, ${underscored_singular_name}_name)
       workspace = workspaces.workspace_or_raise(workspace_name)
-      ${underscored_plural_name} = client.${underscored_plural_name}.get_${underscored_plural_name}_for_workspace(workspace_gid: workspace.gid)
-      ${underscored_plural_name}.find { |${underscored_singular_name}| ${underscored_singular_name}.name == ${underscored_singular_name}_name }
+      ${underscored_singular_name}_objs = client.${underscored_plural_name}.get_${underscored_plural_name}_for_workspace(workspace_gid: workspace.gid)
+      ${underscored_singular_name}_objs.find { |${underscored_singular_name}_obj| ${underscored_singular_name}_obj.name == ${underscored_singular_name}_name }
     end
     cache_method :${underscored_singular_name}, LONG_CACHE_TIME
 
     private
 
-    attr_reader :workspaces, :client
+    # @return [Checkoff::Workspaces]
+    attr_reader :workspaces
+
+    # @return [Asana::Client]
+    attr_reader :client
 
     # bundle exec ./${underscored_plural_name}.rb
     # :nocov:
     class << self
       # @return [void]
       def run
+        # @sg-ignore
+        # @type [String]
         workspace_name = ARGV[0] || raise('Please pass workspace name as first argument')
+        # @sg-ignore
+        # @type [String]
         ${underscored_singular_name}_name = ARGV[1] || raise('Please pass ${underscored_singular_name} name as second argument')
         ${underscored_plural_name} = Checkoff::${class_name}.new
         ${underscored_singular_name} = ${underscored_plural_name}.${underscored_singular_name}_or_raise(workspace_name, ${underscored_singular_name}_name)

data/lib/checkoff/internal/selector_classes/task.rb

@@ -72,7 +72,7 @@ module Checkoff
       end
 
       # :ready function
-      class DuePFunctionEvaluator < FunctionEvaluator
+      class ReadyFunctionEvaluator < FunctionEvaluator
         def matches?
           fn?(selector, :ready)
         end

data/lib/checkoff/portfolios.rb

@@ -0,0 +1,112 @@
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'cache_method'
+require_relative 'internal/config_loader'
+require_relative 'workspaces'
+require_relative 'clients'
+
+# https://developers.asana.com/reference/portfolios
+
+module Checkoff
+  # Pull portfolios from Asana
+  class Portfolios
+    # @!parse
+    #   extend CacheMethod::ClassMethods
+
+    MINUTE = 60
+    HOUR = MINUTE * 60
+    DAY = 24 * HOUR
+    REALLY_LONG_CACHE_TIME = HOUR * 1
+    LONG_CACHE_TIME = MINUTE * 15
+    SHORT_CACHE_TIME = MINUTE
+
+    # @param config [Hash]
+    # @param workspaces [Checkoff::Workspaces]
+    # @param clients [Checkoff::Clients]
+    # @param client [Asana::Client]
+    def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
+                   workspaces: Checkoff::Workspaces.new(config: config),
+                   clients: Checkoff::Clients.new(config: config),
+                   client: clients.client)
+      @workspaces = workspaces
+      @client = client
+    end
+
+    # @param workspace_name [String]
+    # @param portfolio_name [String]
+    #
+    # @return [Asana::Resources::Portfolio]
+    def portfolio_or_raise(workspace_name, portfolio_name)
+      portfolio_obj = portfolio(workspace_name, portfolio_name)
+      raise "Could not find portfolio #{portfolio_name} under workspace #{workspace_name}." if portfolio_obj.nil?
+
+      portfolio_obj
+    end
+    cache_method :portfolio_or_raise, LONG_CACHE_TIME
+
+    # @param workspace_name [String]
+    # @param portfolio_name [String]
+    #
+    # @sg-ignore
+    # @return [Asana::Resources::Portfolio,nil]
+    def portfolio(workspace_name, portfolio_name)
+      workspace = workspaces.workspace_or_raise(workspace_name)
+      me = client.users.me
+      portfolio_objs = client.portfolios.find_all(workspace: workspace.gid,
+                                                  owner: me.gid)
+      # @type [Asana::Resources::Portfolio, nil]
+      portfolio_objs.find { |portfolio_obj| portfolio_obj.name == portfolio_name }
+    end
+    cache_method :portfolio, LONG_CACHE_TIME
+
+    # Pull a specific portfolio by gid
+    #
+    # @param portfolio_gid [String]
+    # @param extra_fields [Array<String>]
+    #
+    # @return [Asana::Resources::Portfolio, nil]
+    def portfolio_by_gid(portfolio_gid,
+                         extra_fields: [])
+      options = {
+        fields: ['name'],
+      }
+      options[:fields] += extra_fields
+      client.portfolios.find_by_id(portfolio_gid, options: options)
+    end
+    cache_method :portfolio_by_gid, SHORT_CACHE_TIME
+
+    private
+
+    # @return [Checkoff::Workspaces]
+    attr_reader :workspaces
+
+    # @return [Asana::Client]
+    attr_reader :client
+
+    # bundle exec ./portfolios.rb
+    # :nocov:
+    class << self
+      # @return [void]
+      def run
+        # @sg-ignore
+        # @type [String]
+        workspace_name = ARGV[0] || raise('Please pass workspace name as first argument')
+        # @sg-ignore
+        # @type [String]
+        portfolio_name = ARGV[1] || raise('Please pass portfolio name as second argument')
+        portfolios = Checkoff::Portfolios.new
+        portfolio = portfolios.portfolio_or_raise(workspace_name, portfolio_name)
+        puts "Results: #{portfolio}"
+      end
+    end
+    # :nocov:
+  end
+end
+
+# :nocov:
+abs_program_name = File.expand_path($PROGRAM_NAME)
+Checkoff::Portfolios.run if abs_program_name == File.expand_path(__FILE__)
+# :nocov:

data/lib/checkoff/version.rb

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

data/lib/checkoff.rb

@@ -3,6 +3,7 @@
 require 'checkoff/version'
 require 'checkoff/clients'
 require 'checkoff/workspaces'
+require 'checkoff/portfolios'
 require 'checkoff/projects'
 require 'checkoff/sections'
 require 'checkoff/subtasks'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: checkoff
 version: !ruby/object:Gem::Version
-  version: 0.91.0
+  version: 0.93.0
 platform: ruby
 authors:
 - Vince Broz
@@ -154,6 +154,7 @@ files:
 - lib/checkoff/internal/selector_evaluator.rb
 - lib/checkoff/internal/task_selector_evaluator.rb
 - lib/checkoff/my_tasks.rb
+- lib/checkoff/portfolios.rb
 - lib/checkoff/project_selectors.rb
 - lib/checkoff/projects.rb
 - lib/checkoff/section_selectors.rb