checkoff 0.97.0 → 0.99.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b1e38f1b4d152c8c28b2ebb2c5a946abe7e2d95ce9650bdf708ecf177afd424
-  data.tar.gz: 55449cde16e497f2332af45b7a8301c926e227c0732c7f0dc4cb9b837ecbf888
+  metadata.gz: f0aa9c88e96e1094d284c59a9c7146ff72f393f2e16442c8e320b3253ab0221d
+  data.tar.gz: 7f6021289d7fb0e331cb6b993b10307287c365d9a00d5fbe789e5b6c13972dad
 SHA512:
-  metadata.gz: 2d8995a72761c9cba456c3c5da9e1cf57d6693018005ccfec14e34db8f9ea82c226628b4794f09fd28495c5b273a06ad1088f6bb5fe01d505d05487c8a754d66
-  data.tar.gz: f295d9173c6e605f250b39a4572cc0148d1a720f10ca0bae3a5157504c5f36003e2f08012e75877fc0dc60f298e8d3916acd41ac03a6f7beb4e45fafd5725c28
+  metadata.gz: ab4476c149bf918e5d138f71a5d1c5df78192f3fa3fa13e8ef0e8a2d7c7198b34268a78ab14e6009237d3cf0113316f3ff91222d22893606c5ecc1ab31830d55
+  data.tar.gz: 4f804bcfc9548b7106fcd80c5764da4250bf024e9dc7f1c2b95460078b89de3a238ba2b28f6d44188cd3fee074a0d348925ef780b751534a0f801f08b74fab24

data/Gemfile.lock

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

data/config/definitions.rb

@@ -42,6 +42,8 @@
 #     module Resources
 #       # https://developers.asana.com/reference/gettask
 #       class Task
+#         # @return [String]
+#         def resource_subtype; end
 #         # @return [String,nil]
 #         def due_at; end
 #         # @return [String,nil]
@@ -136,6 +138,12 @@
 #         # @param project_gid [String]
 #         # @return [Enumerable<Asana::Resources::Section>]
 #         def get_sections_for_project(project_gid:, options: {}); end
+#         # Returns the complete record for a single section.
+#         #
+#         # @param [String] id - The section to get.
+#         # @param options [Hash] - the request I/O options.
+#         # @return [Asana::Resources::Section]
+#         def find_by_id(id, options: {}); end
 #       end
 #       class Project
 #         # Returns the compact project records for all projects in the workspace.

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../function_evaluator'
+require 'checkoff/internal/task_timing'
 
 module Checkoff
   module SelectorClasses
@@ -9,10 +10,14 @@ module Checkoff
       class FunctionEvaluator < ::Checkoff::SelectorClasses::FunctionEvaluator
         # @param selector [Array<(Symbol, Array)>,String]
         # @param tasks [Checkoff::Tasks]
+        # @param timelines [Checkoff::Timelines]
         def initialize(selector:,
-                       tasks:)
+                       tasks:,
+                       timelines:)
           @selector = selector
           @tasks = tasks
+          @timelines = timelines
+          @task_timing = ::Checkoff::Internal::TaskTiming.new
           super()
         end
 
@@ -41,31 +46,6 @@ module Checkoff
           raise "Teach me how to handle field #{field_name}"
         end
 
-        # @param task [Asana::Resources::Task]
-        # @param field_name [Symbol]
-        #
-        # @sg-ignore
-        # @return [Date, Time, nil]
-        def pull_date_or_time_field_by_name(task, field_name)
-          if field_name == :due
-            return Time.parse(task.due_at) unless task.due_at.nil?
-
-            return Date.parse(task.due_on) unless task.due_on.nil?
-
-            return nil
-          end
-
-          if field_name == :start
-            return Time.parse(task.start_at) unless task.start_at.nil?
-
-            return Date.parse(task.start_on) unless task.start_on.nil?
-
-            return nil
-          end
-
-          raise "Teach me how to handle field #{field_name}"
-        end
-
         # @sg-ignore
         # @param task [Asana::Resources::Task]
         # @param custom_field_gid [String]

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

@@ -138,8 +138,8 @@ module Checkoff
           end_n_days_from_now_time = (Time.now + (end_num_days_from_now * 24 * 60 * 60))
 
           # @type [Date, Time, nil]
-          task_date_or_time = pull_date_or_time_field_by_name(task, :start) ||
-                              pull_date_or_time_field_by_name(task, :due)
+          task_date_or_time = @task_timing.date_or_time_field_by_name(task, :start) ||
+                              @task_timing.date_or_time_field_by_name(task, :due)
 
           return false if task_date_or_time.nil?
 
@@ -353,6 +353,26 @@ module Checkoff
           estimate_hours > allocated_hours
         end
       end
+
+      # :dependent_on_previous_section_last_milestone
+      class DependentOnPreviousSectionLastMilestoneFunctionEvaluator < FunctionEvaluator
+        FUNCTION_NAME = :dependent_on_previous_section_last_milestone
+
+        def matches?
+          fn?(selector, FUNCTION_NAME)
+        end
+
+        # @param task [Asana::Resources::Task]
+        # @param project_name [String]
+        # @param limit_to_portfolio_gid [String, nil] If specified,
+        # only projects in this portfolio will be evaluated.
+        #
+        # @return [Boolean]
+        def evaluate(task, limit_to_portfolio_gid: nil)
+          @timelines.task_dependent_on_previous_section_last_milestone?(task,
+                                                                        limit_to_portfolio_gid: limit_to_portfolio_gid)
+        end
+      end
     end
   end
 end

data/lib/checkoff/internal/task_selector_evaluator.rb

@@ -9,10 +9,13 @@ module Checkoff
   class TaskSelectorEvaluator < SelectorEvaluator
     # @param task [Asana::Resources::Task]
     # @param tasks [Checkoff::Tasks]
+    # @param timelines [Checkoff::Timelines]
     def initialize(task:,
-                   tasks: Checkoff::Tasks.new)
+                   tasks: Checkoff::Tasks.new,
+                   timelines: Checkoff::Timelines.new)
       @item = task
       @tasks = tasks
+      @timelines = timelines
       super()
     end
 
@@ -35,12 +38,14 @@ module Checkoff
 
     # @return [Hash]
     def initializer_kwargs
-      { tasks: tasks }
+      { tasks: tasks, timelines: timelines }
     end
 
     # @return [Asana::Resources::Task]
     attr_reader :item
     # @return [Checkoff::Tasks]
     attr_reader :tasks
+    # @return [Checkoff::Timelines]
+    attr_reader :timelines
   end
 end

data/lib/checkoff/internal/task_timing.rb

@@ -5,27 +5,62 @@ module Checkoff
     # Utility methods for working with task dates and times
     class TaskTiming
       # @param time_class [Class<Time>]
-      def initialize(time_class: Time)
+      # @param date_class [Class<Date>]
+      def initialize(time_class: Time, date_class: Date)
         @time_class = time_class
+        @date_class = date_class
       end
 
       # @param task [Asana::Resources::Task]
       # @return [Time, nil]
       def start_time(task)
-        return @time_class.parse(task.start_at) if task.start_at
-        return @time_class.parse(task.start_on) if task.start_on
-
-        nil
+        date_or_time_field_by_name(task, :start)&.to_time
       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
+        date_or_time_field_by_name(task, :due)&.to_time
+      end
+
+      # @param task [Asana::Resources::Task]
+      # @param field_name [Symbol]
+      #
+      # @sg-ignore
+      # @return [Date, Time, nil]
+      def start_date_or_time(task)
+        return @time_class.parse(task.start_at) unless task.start_at.nil?
+
+        return @date_class.parse(task.start_on) unless task.start_on.nil?
 
         nil
       end
+
+      # @param task [Asana::Resources::Task]
+      # @param field_name [Symbol]
+      #
+      # @sg-ignore
+      # @return [Date, Time, nil]
+      def due_date_or_time(task)
+        return @time_class.parse(task.due_at) unless task.due_at.nil?
+
+        return @date_class.parse(task.due_on) unless task.due_on.nil?
+
+        nil
+      end
+
+      # @param task [Asana::Resources::Task]
+      # @param field_name [Symbol]
+      #
+      # @sg-ignore
+      # @return [Date, Time, nil]
+      def date_or_time_field_by_name(task, field_name)
+        return due_date_or_time(task) if field_name == :due
+
+        return start_date_or_time(task) if field_name == :start
+
+        raise "Teach me how to handle field #{field_name}"
+      end
     end
   end
 end

data/lib/checkoff/sections.rb

@@ -56,13 +56,23 @@ module Checkoff
     #
     # @return [Enumerable<Asana::Resources::Section>]
     def sections_or_raise(workspace_name, project_name, extra_fields: [])
-      fields = %w[name] + extra_fields
       project = project_or_raise(workspace_name, project_name)
-      client.sections.get_sections_for_project(project_gid: project.gid,
-                                               options: { fields: fields })
+      sections_by_project_gid(project.gid, extra_fields: extra_fields)
     end
     cache_method :sections_or_raise, SHORT_CACHE_TIME
 
+    # Returns a list of Asana API section objects for a given project GID
+    # @param project_gid [String]
+    # @param extra_fields [Array<String>]
+    #
+    # @return [Enumerable<Asana::Resources::Section>]
+    def sections_by_project_gid(project_gid, extra_fields: [])
+      fields = %w[name] + extra_fields
+      client.sections.get_sections_for_project(project_gid: project_gid,
+                                               options: { fields: fields })
+    end
+    cache_method :sections_by_project_gid, SHORT_CACHE_TIME
+
     # Given a workspace name and project name, then provide a Hash of
     # tasks with section name -> task list of the uncompleted tasks
     # @param workspace_name [String]
@@ -85,6 +95,20 @@ module Checkoff
       end
     end
 
+    # @param section_gid [String]
+    # @param only_uncompleted [Boolean]
+    # @param extra_fields [Array<String>]
+    #
+    # @return [Enumerable<Asana::Resources::Task>]
+    def tasks_by_section_gid(section_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.get_tasks(section: section_gid, **options)
+    end
+
     # XXX: Rename to section_tasks
     #
     # Pulls task objects from a specified section
@@ -147,8 +171,45 @@ module Checkoff
       name
     end
 
+    # @param section [Asana::Resources::Section]
+    #
+    # @return [Asana::Resources::Section, nil]
+    def previous_section(section)
+      sections = sections_by_project_gid(section.project.fetch('gid'))
+
+      # @type [Array<Asana::Resources::Section>]
+      sections = sections.to_a
+
+      index = sections.find_index { |s| s.gid == section.gid }
+      return nil if index.nil? || index.zero?
+
+      sections[index - 1]
+    end
+    cache_method :previous_section, SHORT_CACHE_TIME
+
+    # @param gid [String]
+    #
+    # @return [Asana::Resources::Section]
+    def section_by_gid(gid)
+      options = {}
+      Asana::Resources::Section.new(parse(client.get("/sections/#{gid}", options: options)).first,
+                                    client: client)
+    end
+
     private
 
+    # https://github.com/Asana/ruby-asana/blob/master/lib/asana/resource_includes/response_helper.rb#L7
+    # @param response [Faraday::Response]
+    #
+    # @return [Array<Hash, Hash>]
+    def parse(response)
+      data = response.body.fetch('data') do
+        raise("Unexpected response body: #{response.body}")
+      end
+      extra = response.body.except('data')
+      [data, extra]
+    end
+
     # @return [Asana::Client]
     attr_reader :client
 
@@ -188,6 +249,7 @@ module Checkoff
     # @param project_gid [String]
     # @return [void]
     def file_task_by_section(by_section, task, project_gid)
+      # @sg-ignore
       # @type [Array<Hash>]
       membership = task.memberships.find { |m| m['project']['gid'] == project_gid }
       raise "Could not find task in project_gid #{project_gid}: #{task}" if membership.nil?

data/lib/checkoff/task_selectors.rb

@@ -23,12 +23,16 @@ module Checkoff
     # @param [Hash] config
     # @param [Asana::Client] client
     # @param [Checkoff::Tasks] tasks
+    # @param [Checkoff::Timelines] timelines
     def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    client: Checkoff::Clients.new(config: config).client,
                    tasks: Checkoff::Tasks.new(config: config,
-                                              client: client))
+                                              client: client),
+                   timelines: Checkoff::Timelines.new(config: config,
+                                                      client: client))
       @config = config
       @tasks = tasks
+      @timelines = timelines
     end
 
     # @param [Asana::Resources::Task] task
@@ -36,7 +40,7 @@ module Checkoff
     #        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)
+      evaluator = TaskSelectorEvaluator.new(task: task, tasks: tasks, timelines: timelines)
       evaluator.evaluate(task_selector)
     end
 
@@ -45,6 +49,9 @@ module Checkoff
     # @return [Checkoff::Tasks]
     attr_reader :tasks
 
+    # @return [Checkoff::Timelines]
+    attr_reader :timelines
+
     # bundle exec ./task_selectors.rb
     # :nocov:
     class << self

data/lib/checkoff/tasks.rb

@@ -27,6 +27,7 @@ module Checkoff
     # @param workspaces [Checkoff::Workspaces]
     # @param sections [Checkoff::Sections]
     # @param time_class [Class<Time>]
+    # @param date_class [Class<Date>]
     # @param asana_task [Class<Asana::Resources::Task>]
     def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    client: Checkoff::Clients.new(config: config).client,
@@ -35,10 +36,12 @@ module Checkoff
                    sections: Checkoff::Sections.new(config: config,
                                                     client: client),
                    time_class: Time,
+                   date_class: Date,
                    asana_task: Asana::Resources::Task)
       @config = config
       @sections = sections
       @time_class = time_class
+      @date_class = date_class
       @asana_task = asana_task
       @client = client
       @workspaces = workspaces
@@ -167,7 +170,7 @@ module Checkoff
 
     # @return [Checkoff::Internal::TaskTiming]
     def task_timing
-      @task_timing ||= Checkoff::Internal::TaskTiming.new(time_class: @time_class)
+      @task_timing ||= Checkoff::Internal::TaskTiming.new(time_class: @time_class, date_class: @date_class)
     end
 
     # @return [Checkoff::Internal::TaskHashes]

data/lib/checkoff/timelines.rb

@@ -0,0 +1,121 @@
+#!/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/timelines
+
+module Checkoff
+  # Manages timelines of dependent tasks with dates and milestones
+  class Timelines
+    # @!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 sections [Checkoff::Sections]
+    # @param tasks [Checkoff::Tasks]
+    # @param clients [Checkoff::Clients]
+    # @param client [Asana::Client]
+    def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
+                   workspaces: Checkoff::Workspaces.new(config: config),
+                   sections: Checkoff::Sections.new(config: config),
+                   tasks: Checkoff::Tasks.new(config: config),
+                   clients: Checkoff::Clients.new(config: config),
+                   client: clients.client)
+      @workspaces = workspaces
+      @sections = sections
+      @tasks = tasks
+      @client = client
+    end
+
+    # @param task [Asana::Resources::Task]
+    # @param limit_to_portfolio_gid [String, nil]
+    # @param project_name [String]
+    def task_dependent_on_previous_section_last_milestone?(task, limit_to_portfolio_gid: nil)
+      task_data = @tasks.task_to_h(task)
+      # @sg-ignore
+      # @type [Array<Hash{String => Hash{String => String}}>]
+      memberships_data = task_data.fetch('memberships')
+      memberships_data.all? do |membership_data|
+        # @type [Hash{String => String}]
+        section_data = membership_data.fetch('section')
+        section_gid = section_data.fetch('gid')
+        section = @sections.section_by_gid(section_gid)
+        task_data_dependent_on_previous_section_last_milestone?(task_data, section)
+      end
+    end
+
+    # @param section_gid [String]
+    #
+    # @return [Asana::Resources::Task,nil]
+    def last_milestone_in_section(section_gid)
+      # @type [Array<Asana::Resources::Task>]
+      task_list = @sections.tasks_by_section_gid(section_gid).to_a
+      last_task = task_list.last
+      last_task&.resource_subtype == 'milestone' ? last_task : nil
+    end
+
+    private
+
+    # @param task_data [Hash]
+    # @param section [Asana::Resources::Section]
+    #
+    # @return [Boolean]
+    def task_data_dependent_on_previous_section_last_milestone?(task_data, section)
+      # @sg-ignore
+      # @type [Array<Hash{String => String}>]
+      dependencies = task_data.fetch('dependencies')
+      return false if dependencies.empty?
+
+      previous_section = @sections.previous_section(section)
+      return false if previous_section.nil?
+
+      previous_section_last_milestone = last_milestone_in_section(previous_section.gid)
+      return false if previous_section_last_milestone.nil?
+
+      dependencies.any? { |dependency| dependency.fetch('gid') == previous_section_last_milestone.gid }
+    end
+
+    # @return [Checkoff::Workspaces]
+    attr_reader :workspaces
+
+    # @return [Asana::Client]
+    attr_reader :client
+
+    # bundle exec ./timelines.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]
+        # timeline_name = ARGV[1] || raise('Please pass timeline name as second argument')
+        # timelines = Checkoff::Timelines.new
+        # timeline = timelines.timeline_or_raise(workspace_name, timeline_name)
+        # puts "Results: #{timeline}"
+      end
+    end
+    # :nocov:
+  end
+end
+
+# :nocov:
+abs_program_name = File.expand_path($PROGRAM_NAME)
+Checkoff::Timelines.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.97.0'
+  VERSION = '0.99.0'
 end

data/lib/checkoff.rb

@@ -8,6 +8,7 @@ require 'checkoff/projects'
 require 'checkoff/sections'
 require 'checkoff/subtasks'
 require 'checkoff/timing'
+require 'checkoff/timelines'
 require 'checkoff/tasks'
 require 'checkoff/custom_fields'
 require 'checkoff/tags'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: checkoff
 version: !ruby/object:Gem::Version
-  version: 0.97.0
+  version: 0.99.0
 platform: ruby
 authors:
 - Vince Broz
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-10-25 00:00:00.000000000 Z
+date: 2023-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -166,6 +166,7 @@ files:
 - lib/checkoff/task_searches.rb
 - lib/checkoff/task_selectors.rb
 - lib/checkoff/tasks.rb
+- lib/checkoff/timelines.rb
 - lib/checkoff/timing.rb
 - lib/checkoff/version.rb
 - lib/checkoff/workspaces.rb