checkoff 0.17.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 934e52a0b06388d6c1dbadb1ff9890cdf74da88f95d9350af04beba49d4021cd
-  data.tar.gz: 1f8780b895c7be869384afc71e7e1187d7e6594dd9139cc951d5330c46028929
+  metadata.gz: 15d4e2598851192dcb2d19e4c2b501d57de3d6deca0f876af8f99402b5d8cb1c
+  data.tar.gz: 2a6db316719696b5736cfc3059b947361184ce3218dd835d44eb5db99ccb1df5
 SHA512:
-  metadata.gz: ac4dd6171e0867c4209bdd8b3b1e166164ab69b633e283d3985b3054c5a32aa81a076f573034584cfeece30312ea909ce0643850b49e7c5d1436ff75a0bc8cc8
-  data.tar.gz: 14e79f6ffc230d038cbb514dca84a34465c4f6aab7052b98f6de25dc63b1f3ca1507ab4a1b108da48e918da0f19ac10657d24f3e94d5610881379d0aafca6f4d
+  metadata.gz: 9bb9300d617321073e23c103bf87471e1f38562171099c5a1ad010e6d9a06d6d0829a66ced957a15859810bfcffca8b3f4281e580f5bb1b8000593c9a4887331
+  data.tar.gz: 91a9629fbd6b42386a4ca8aed172c27b8fe9bf2edd2c7656265051d0dd990ffe12700aaeb1df215c40eb1b64983888adac2252933246f4920a564ba7237c788a

data/.envrc

@@ -1,4 +1,4 @@
 # shellcheck shell=bash
 PATH_add bin
-export ASANA__PERSONAL_ACCESS_TOKEN="op://Private/Asana access token - VLD read-write/token" ASANA__DEFAULT_ASSIGNEE_GID="op://Private/Asana access token - VLD read-write/default_workspace_gid"
+export ASANA__PERSONAL_ACCESS_TOKEN="op://Private/Asana access token - VLD read-write/token" ASANA__DEFAULT_ASSIGNEE_GID="op://Private/Asana access token - VLD read-write/default_workspace_gid" ASANA__DEFAULT_WORKSPACE_GID="op://Private/Asana access token - VLD read-write/default_workspace_gid"
 direnv_load with-op op run --cache -- direnv dump

data/.gitignore

@@ -62,4 +62,3 @@ requirements_dev.txt.installed
 /coverage/assets/
 /coverage/index.html
 /coverage/lcov/
-/pkg

data/.markdownlint_style.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+rule 'MD029', style: 'ordered'

data/.mdlrc

@@ -0,0 +1 @@
+style ".markdownlint_style.rb"

data/CONTRIBUTING.rst

@@ -0,0 +1,75 @@
+============
+Contributing
+============
+
+Contributions are welcome, and they are greatly appreciated! Every little bit
+helps, and credit will always be given.
+
+You can contribute in many ways:
+
+Types of Contributions
+----------------------
+
+Report Bugs
+~~~~~~~~~~~
+
+Report bugs at https://github.com/apiology/checkoff/issues
+
+If you are reporting a bug, please include:
+
+* Your operating system name and version.
+* Any details about your local setup that might be helpful in troubleshooting.
+* Detailed steps to reproduce the bug.
+
+Fix Bugs
+~~~~~~~~
+
+Look through the GitHub issues for bugs. Anything tagged with "bug"
+and "help wanted" is open to whoever wants to implement a fix for it.
+
+Implement Features
+~~~~~~~~~~~~~~~~~~
+
+Look through the GitHub issues for features. Anything tagged with "enhancement"
+and "help wanted" is open to whoever wants to implement it.
+
+If you have a new feature in mind, please start it by filing an issue
+so we can discuss the need and approach before you invest time into
+coding it.
+
+Write Documentation
+~~~~~~~~~~~~~~~~~~~
+
+Checkoff could always use more documentation, whether as part of
+the official Checkoff docs, in docstrings, or even on the web in blog posts, articles,
+and such.
+
+Submit Feedback
+~~~~~~~~~~~~~~~
+
+The best way to send feedback is to file an issue at
+https://github.com/apiology/checkoff/issues.
+
+If you are proposing a new feature:
+
+* Explain in detail how it would work.
+* Keep the scope as narrow as possible, to make it easier to implement.
+* Remember that this is a volunteer-driven project, and that contributions
+  are welcome :)
+
+Get Started!
+------------
+
+Ready to contribute?  See DEVELOPMENT.md in this directory for details
+on how to set yourself up for local development.
+
+Pull Request Guidelines
+-----------------------
+
+Before you submit a pull request, check that it meets these guidelines:
+
+1. The pull request should include tests.
+
+2. If the pull request adds functionality, the docs should be updated. Put your
+   new functionality into a function with a docstring, and add the feature to
+   the list in README.md.

data/DEVELOPMENT.md

@@ -57,4 +57,13 @@ git log "v$(bump current)..."
 bump --tag --tag-prefix=v ${type_of_bump:?}
 rake release
 git push
+git push --tags
+```
+
+
+## Developing
+
+```sh
+bundle install
+bundle exec exe/checkoff --help
 ```

data/Gemfile.lock

@@ -12,7 +12,7 @@ GIT
 PATH
   remote: .
   specs:
-    checkoff (0.17.0)
+    checkoff (0.19.0)
       activesupport
       asana (> 0.10.0)
       cache_method
@@ -22,7 +22,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (6.1.5.1)
+    activesupport (6.1.6.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -33,10 +33,12 @@ GEM
     cache (0.4.1)
     cache_method (0.2.7)
       cache (>= 0.2.1)
+    chef-utils (17.10.0)
+      concurrent-ruby
     childprocess (4.0.0)
     coderay (1.1.3)
     concurrent-ruby (1.1.10)
-    dalli (3.2.1)
+    dalli (3.2.2)
     docile (1.4.0)
     faraday (1.5.1)
       faraday-em_http (~> 1.0)
@@ -61,15 +63,30 @@ GEM
       faraday_middleware
       multi_json
     gli (2.21.0)
-    i18n (1.10.0)
+    i18n (1.12.0)
       concurrent-ruby (~> 1.0)
     imagen (0.1.8)
       parser (>= 2.5, != 2.5.1.1)
     iniparse (1.5.0)
     jwt (2.2.3)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    mdl (0.11.0)
+      kramdown (~> 2.3)
+      kramdown-parser-gfm (~> 1.1)
+      mixlib-cli (~> 2.1, >= 2.1.1)
+      mixlib-config (>= 2.2.1, < 4)
+      mixlib-shellout
     method_source (1.0.0)
-    minitest (5.15.0)
+    minitest (5.16.2)
     minitest-profile (0.0.2)
+    mixlib-cli (2.1.8)
+    mixlib-config (3.0.27)
+      tomlrb
+    mixlib-shellout (3.2.7)
+      chef-utils
     mocha (1.12.0)
     multi_json (1.15.0)
     multi_xml (0.6.0)
@@ -90,7 +107,7 @@ GEM
     pry (0.14.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    rack (2.2.3)
+    rack (2.2.4)
     rainbow (3.0.0)
     rake (13.0.3)
     regexp_parser (2.1.1)
@@ -120,14 +137,15 @@ GEM
     simplecov-html (0.12.3)
     simplecov-lcov (0.8.0)
     simplecov_json_formatter (0.1.3)
-    tzinfo (2.0.4)
+    tomlrb (2.0.3)
+    tzinfo (2.0.5)
       concurrent-ruby (~> 1.0)
     undercover (0.4.3)
       imagen (>= 0.1.8)
       rainbow (>= 2.1, < 4.0)
       rugged (>= 0.27, < 1.2)
     unicode-display_width (2.0.0)
-    zeitwerk (2.5.4)
+    zeitwerk (2.6.0)
 
 PLATFORMS
   ruby
@@ -140,6 +158,7 @@ DEPENDENCIES
   bump
   bundler
   checkoff!
+  mdl
   minitest-profile
   mocha
   overcommit (>= 0.58.0)

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021, Vince Broz
+Copyright (c) 2016-2022, Vince Broz
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,4 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-

data/Makefile

@@ -39,6 +39,9 @@ clear_metrics: ## remove or reset result artifacts created by tests and quality
 
 clean: clear_metrics ## remove all built artifacts
 
+
+typecheck: ## validate types in code and configuration
+
 overcommit: ## run precommit quality checks
 	bundle exec overcommit --run
 

data/README.md

@@ -149,18 +149,14 @@ personal_access_token: 'some_big_long_string_from_asana.com_here'
 
 Alternately you can set environment variables to match - e.g., `ASANA__PERSONAL_ACCESS_TOKEN`
 
-## Developing
+## Contributions
 
-```sh
-bundle install
-bundle exec exe/checkoff --help
-```
+This project, as with all others, rests on the shoulders of a broad
+ecosystem supported by many volunteers doing thankless work, along
+with specific contributors.
 
-To publish new version as a maintainer:
+In particular I'd like to call out:
 
-```sh
-git log "v$(bump current)..."
-# Set type_of_bump to patch, minor, or major
-bump --tag --tag-prefix=v ${type_of_bump:?}
-rake release
-```
+* [Audrey Roy Greenfeld](https://github.com/audreyfeldroy) for the
+  cookiecutter tool and associated examples, which keep my many
+  projects building with shared boilerplate with a minimum of fuss.

data/checkoff.gemspec

@@ -32,6 +32,7 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'bump'
   spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'mdl'
   spec.add_development_dependency 'minitest-profile'
   spec.add_development_dependency 'mocha'
   # 0.58.0 and 0.57.0 don't seem super compatible with signatures, and

data/coverage/.last_run.json

@@ -1,6 +1,6 @@
 {
   "result": {
-    "line": 99.78,
-    "branch": 93.33
+    "line": 99.61,
+    "branch": 88.05
   }
 }

data/fix.sh

@@ -284,12 +284,7 @@ ensure_python_versions() {
       }
 
       major_minor="$(cut -d. -f1-2 <<<"${ver}")"
-      if [ "${major_minor}" == 3.6 ]
-      then
-        pyenv_install --patch "${ver}" < <(curl -sSL https://github.com/python/cpython/commit/8ea6353.patch\?full_index=1)
-      else
-        pyenv_install "${ver}"
-      fi
+      pyenv_install "${ver}"
     else
       pyenv install -s "${ver}"
     fi
@@ -307,12 +302,12 @@ ensure_pyenv_virtualenvs() {
 }
 
 ensure_pip_and_wheel() {
-  # Make sure we have a pip with the 20.3 resolver, and after the
-  # initial bugfix release
+  # pip 22 seems to be better at finding pandas pre-compiled wheels
+  # for macOS, so let's make sure we're using at least that version
   major_pip_version=$(pip --version | cut -d' ' -f2 | cut -d '.' -f 1)
   if [[ major_pip_version -lt 21 ]]
   then
-    pip install 'pip>=20.3.1'
+    pip install 'pip>=22'
   fi
   # wheel is helpful for being able to cache long package builds
   pip show wheel >/dev/null 2>&1 || pip install wheel

data/lib/checkoff/cli.rb

@@ -61,7 +61,7 @@ module Checkoff
                    to_workspace_arg:,
                    to_project_arg:,
                    to_section_arg:,
-                   config: Checkoff::ConfigLoader.load(:asana),
+                   config: Checkoff::Internal::ConfigLoader.load(:asana),
                    projects: Checkoff::Projects.new(config: config),
                    sections: Checkoff::Sections.new(config: config),
                    logger: $stderr)
@@ -122,7 +122,7 @@ module Checkoff
   class ViewSubcommand
     def initialize(workspace_name, project_name, section_name,
                    task_name,
-                   config: Checkoff::ConfigLoader.load(:asana),
+                   config: Checkoff::Internal::ConfigLoader.load(:asana),
                    projects: Checkoff::Projects.new(config: config),
                    sections: Checkoff::Sections.new(config: config,
                                                     projects: projects),
@@ -201,7 +201,7 @@ module Checkoff
   # CLI subcommand that creates a task
   class QuickaddSubcommand
     def initialize(workspace_name, task_name,
-                   config: Checkoff::ConfigLoader.load(:asana),
+                   config: Checkoff::Internal::ConfigLoader.load(:asana),
                    workspaces: Checkoff::Workspaces.new(config: config),
                    tasks: Checkoff::Tasks.new(config: config))
       @workspace_name = workspace_name

data/lib/checkoff/clients.rb

@@ -3,7 +3,7 @@
 # frozen_string_literal: true
 
 require 'forwardable'
-require_relative 'config_loader'
+require_relative 'internal/config_loader'
 require 'asana'
 
 # https://developers.asana.com/docs/clients
@@ -18,7 +18,7 @@ module Checkoff
     LONG_CACHE_TIME = MINUTE * 15
     SHORT_CACHE_TIME = MINUTE
 
-    def initialize(config: Checkoff::ConfigLoader.load(:asana),
+    def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    asana_client_class: Asana::Client)
       @config = config
       @asana_client_class = asana_client_class

data/lib/checkoff/create-entity.sh

@@ -16,7 +16,7 @@ cat > "${underscored_plural_name}.rb" << EOF
 
 require 'forwardable'
 require 'cache_method'
-require_relative 'config_loader'
+require_relative 'internal/config_loader'
 require_relative 'workspaces'
 require_relative 'clients'
 
@@ -31,7 +31,7 @@ module Checkoff
     LONG_CACHE_TIME = MINUTE * 15
     SHORT_CACHE_TIME = MINUTE
 
-    def initialize(config: Checkoff::ConfigLoader.load(:asana),
+    def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    workspaces: Checkoff::Workspaces.new(config: config),
                    clients: Checkoff::Clients.new(config: config),
                    client: clients.client)

data/lib/checkoff/custom_fields.rb

@@ -4,7 +4,7 @@
 
 require 'forwardable'
 require 'cache_method'
-require_relative 'config_loader'
+require_relative 'internal/config_loader'
 require_relative 'workspaces'
 require_relative 'clients'
 
@@ -20,7 +20,7 @@ module Checkoff
     LONG_CACHE_TIME = MINUTE * 15
     SHORT_CACHE_TIME = MINUTE
 
-    def initialize(config: Checkoff::ConfigLoader.load(:asana),
+    def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    workspaces: Checkoff::Workspaces.new(config: config),
                    clients: Checkoff::Clients.new(config: config),
                    client: clients.client)

data/lib/checkoff/internal/config_loader.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'active_support/core_ext/hash'
+
+module Checkoff
+  module Internal
+    # Use the provided config from a YAML file, and fall back to env
+    # variable if it's not populated for a key'
+    class EnvFallbackConfigLoader
+      def initialize(config, sym, yaml_filename)
+        @config = config
+        @envvar_prefix = sym.upcase
+        @yaml_filename = yaml_filename
+      end
+
+      def [](key)
+        config_value = @config[key]
+        return config_value unless config_value.nil?
+
+        ENV[envvar_name(key)]
+      end
+
+      def fetch(key)
+        out = self[key]
+        return out unless out.nil?
+
+        raise KeyError,
+              "Please configure either the #{key} key in #{@yaml_filename} or set #{envvar_name(key)}"
+      end
+
+      private
+
+      def envvar_name(key)
+        "#{@envvar_prefix}__#{key.upcase}"
+      end
+    end
+
+    # Load configuration file
+    class ConfigLoader
+      class << self
+        def load(sym)
+          yaml_result = load_yaml_file(sym)
+          EnvFallbackConfigLoader.new(yaml_result, sym, yaml_filename(sym))
+        end
+
+        private
+
+        def load_yaml_file(sym)
+          filename = yaml_filename(sym)
+          return {} unless File.exist?(filename)
+
+          YAML.load_file(filename).with_indifferent_access
+        end
+
+        def yaml_filename(sym)
+          file = "#{sym}.yml"
+          File.expand_path("~/.#{file}")
+        end
+      end
+    end
+  end
+end

data/lib/checkoff/internal/create-class.sh

@@ -0,0 +1,22 @@
+#!/bin/bash -eu
+
+set -o pipefail
+
+underscored_plural_name="${1:?underscored plural name of entities minus .rb}"
+class_name="${2:?class name without Checkoff:: prefix}"
+
+cat > "${underscored_plural_name}.rb" << EOF
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+module Checkoff
+  module Internal
+    class ${class_name}
+      def initialize(_deps = {}); end
+    end
+  end
+end
+EOF
+
+git add "${underscored_plural_name}.rb"

data/lib/checkoff/internal/search_url_parser.rb

@@ -0,0 +1,213 @@
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+module Checkoff
+  module Internal
+    # base class for handling different custom_field_#{gid}.variant params
+    class CustomFieldVariant
+      def initialize(gid, remaining_params)
+        @gid = gid
+        @remaining_params = remaining_params
+      end
+
+      private
+
+      attr_reader :gid, :remaining_params
+    end
+
+    # custom_field_#{gid}.variant = 'less_than'
+    class LessThanCustomFieldVariant < CustomFieldVariant
+      def convert
+        max_param = "custom_field_#{gid}.max"
+        case remaining_params.keys
+        when [max_param]
+          convert_single_custom_field_less_than_params_max_param(max_param)
+        else
+          raise "Teach me how to handle #{remaining_params}"
+        end
+      end
+
+      private
+
+      def convert_single_custom_field_less_than_params_max_param(max_param)
+        max_values = remaining_params.fetch(max_param)
+        unless max_values.length == 1
+          raise "Teach me how to handle these remaining keys for #{max_param}: #{remaining_params}"
+        end
+
+        max_value = max_values[0]
+        empty_task_selector = []
+        [{ "custom_fields.#{gid}.less_than" => max_value }, empty_task_selector]
+      end
+    end
+
+    # custom_field_#{gid}.variant = 'is_not'
+    class IsNotCustomFieldVariant < CustomFieldVariant
+      def convert
+        case remaining_params.keys
+        when ["custom_field_#{gid}.selected_options"]
+          convert_single_custom_field_is_not_params_selected_options
+        else
+          raise "Teach me how to handle #{remaining_params}"
+        end
+      end
+
+      private
+
+      def convert_single_custom_field_is_not_params_selected_options
+        selected_options = remaining_params.fetch("custom_field_#{gid}.selected_options")
+        raise "Teach me how to handle #{remaining_params}" unless selected_options.length == 1
+
+        [{ "custom_fields.#{gid}.is_set" => 'true' },
+         ['not',
+          ['custom_field_gid_value_contains_any_gid',
+           gid,
+           selected_options.fetch(0).split('~')]]]
+      end
+    end
+
+    # custom_field_#{gid}.variant = 'no_value'
+    class NoValueCustomFieldVariant < CustomFieldVariant
+      def convert
+        unless remaining_params.length.zero?
+          raise "Teach me how to handle these remaining keys for #{variant_key}: #{remaining_params}"
+        end
+
+        empty_task_selector = []
+        [{ "custom_fields.#{gid}.is_set" => 'false' }, empty_task_selector]
+      end
+    end
+
+    # custom_field_#{gid}.variant = 'is'
+    class IsCustomFieldVariant < CustomFieldVariant
+      def convert
+        unless remaining_params.length == 1
+          raise "Teach me how to handle these remaining keys for #{variant_key}: #{remaining_params}"
+        end
+
+        key, values = remaining_params.to_a[0]
+        convert_custom_field_is_arg(key, values)
+      end
+
+      private
+
+      def convert_custom_field_is_arg(key, values)
+        empty_task_selector = []
+
+        if key.end_with? '.selected_options'
+          raise "Too many values found for #{key}: #{values}" if values.length != 1
+
+          return [{ "custom_fields.#{gid}.value" => values[0] },
+                  empty_task_selector]
+        end
+
+        raise "Teach me how to handle #{key} = #{values}"
+      end
+    end
+
+    # Convert custom field parameters from an Asana search URL into
+    # API search arguments and Checkoff task selectors
+    class CustomFieldParamConverter
+      def initialize(custom_field_params:)
+        @custom_field_params = custom_field_params
+      end
+
+      def convert
+        args = {}
+        task_selector = []
+        by_custom_field.each do |gid, single_custom_field_params|
+          new_args, new_task_selector = convert_single_custom_field_params(gid,
+                                                                           single_custom_field_params)
+          args, task_selector = merge_args_and_task_selectors(args, new_args,
+                                                              task_selector, new_task_selector)
+        end
+        [args, task_selector]
+      end
+
+      private
+
+      def by_custom_field
+        custom_field_params.group_by do |key, _value|
+          gid_from_custom_field_key(key)
+        end.transform_values(&:to_h)
+      end
+
+      def merge_args_and_task_selectors(args, new_args, task_selector, new_task_selector)
+        args = args.merge(new_args)
+        return [args, task_selector] if new_task_selector == []
+
+        raise 'Teach me how to merge task selectors' unless task_selector == []
+
+        task_selector = new_task_selector
+
+        [args, task_selector]
+      end
+
+      VARIANTS = {
+        'is' => IsCustomFieldVariant,
+        'no_value' => NoValueCustomFieldVariant,
+        'is_not' => IsNotCustomFieldVariant,
+        'less_than' => LessThanCustomFieldVariant,
+      }.freeze
+
+      def convert_single_custom_field_params(gid, single_custom_field_params)
+        variant_key = "custom_field_#{gid}.variant"
+        variant = single_custom_field_params.fetch(variant_key)
+        remaining_params = single_custom_field_params.reject { |k, _v| k == variant_key }
+        raise "Teach me how to handle #{variant_key} = #{variant}" unless variant.length == 1
+
+        variant_class = VARIANTS[variant[0]]
+        return variant_class.new(gid, remaining_params).convert unless variant_class.nil?
+
+        raise "Teach me how to handle #{variant_key} = #{variant}"
+      end
+
+      def gid_from_custom_field_key(key)
+        key.split('_')[2].split('.')[0]
+      end
+
+      attr_reader :custom_field_params
+    end
+
+    # Parse Asana search URLs into parameters suitable to pass into
+    # the /workspaces/{workspace_gid}/tasks/search endpoint
+    class SearchUrlParser
+      def initialize(_deps = {}); end
+
+      def convert_params(url)
+        url_params = CGI.parse(URI.parse(url).query)
+        custom_field_params, regular_url_params = partition_url_params(url_params)
+        custom_field_args, task_selector = convert_custom_field_params(custom_field_params)
+        regular_url_args = convert_regular_params(regular_url_params)
+        [custom_field_args.merge(regular_url_args), task_selector]
+      end
+
+      private
+
+      def convert_regular_params(regular_url_params)
+        regular_url_params.to_a.map do |key, values|
+          convert_arg(key, values)
+        end.to_h
+      end
+
+      def convert_custom_field_params(custom_field_params)
+        CustomFieldParamConverter.new(custom_field_params: custom_field_params).convert
+      end
+
+      def partition_url_params(url_params)
+        url_params.to_a.partition do |key, _values|
+          key.start_with? 'custom_field_'
+        end.map(&:to_h)
+      end
+
+      PARAM_MAP = {
+        'any_projects.ids' => 'projects.any',
+      }.freeze
+
+      def convert_arg(key, values)
+        [PARAM_MAP.fetch(key), values.join(',')]
+      end
+    end
+  end
+end

data/lib/checkoff/internal/task_selector_evaluator.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Checkoff
+  # Base class to evaluate a task selector function given fully evaluated arguments
+  class FunctionEvaluator
+    def initialize(task_selector:)
+      @task_selector = task_selector
+    end
+
+    def evaluate_arg?(_index)
+      true
+    end
+
+    private
+
+    def fn?(object, fn_name)
+      object.is_a?(Array) && !object.empty? && [fn_name, fn_name.to_s].include?(object[0])
+    end
+
+    attr_reader :task_selector
+  end
+
+  # :not function
+  class NotFunctionEvaluator < FunctionEvaluator
+    def matches?
+      fn?(task_selector, :not)
+    end
+
+    def evaluate(_task, subvalue)
+      !subvalue
+    end
+  end
+
+  # :nil? function
+  class NilPFunctionEvaluator < FunctionEvaluator
+    def matches?
+      fn?(task_selector, :nil?)
+    end
+
+    def evaluate(_task, subvalue)
+      subvalue.nil?
+    end
+  end
+
+  # :tag function
+  class TagPFunctionEvaluator < FunctionEvaluator
+    def matches?
+      fn?(task_selector, :tag)
+    end
+
+    def evaluate_arg?(_index)
+      false
+    end
+
+    def evaluate(task, tag_name)
+      task.tags.map(&:name).include? tag_name
+    end
+  end
+
+  # :custom_field_value function
+  class CustomFieldValueFunctionEvaluator < FunctionEvaluator
+    def matches?
+      fn?(task_selector, :custom_field_value)
+    end
+
+    def evaluate_arg?(_index)
+      false
+    end
+
+    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 }
+      return nil if custom_field.nil?
+
+      custom_field['display_value']
+    end
+  end
+
+  # :custom_field_gid_value_contains_any_gid function
+  class CustomFieldGidValueContainsAnyGidFunctionEvaluator < FunctionEvaluator
+    def matches?
+      fn?(task_selector, :custom_field_gid_value_contains_any_gid)
+    end
+
+    def evaluate_arg?(_index)
+      false
+    end
+
+    def evaluate(task, custom_field_gid, custom_field_values_gids)
+      actual_custom_field_values_gids = pull_custom_field_values_gids(task, custom_field_gid)
+
+      (custom_field_values_gids - actual_custom_field_values_gids).empty?
+    end
+
+    private
+
+    def pull_custom_field_or_raise(task, custom_field_gid)
+      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
+
+      matched_custom_field = custom_fields.find { |data| data.fetch('gid') == custom_field_gid }
+      raise "Could not find custom field with gid #{custom_field_gid}" if matched_custom_field.nil?
+
+      matched_custom_field
+    end
+
+    def pull_custom_field_values_gids(task, custom_field_gid)
+      matched_custom_field = pull_custom_field_or_raise(task, custom_field_gid)
+
+      enum_value = matched_custom_field.fetch('enum_value')
+      actual_custom_field_values_gids = []
+      unless enum_value.nil?
+        if enum_value.fetch('enabled') == false
+          raise "Unexpected enabled value on custom field: #{matched_custom_field}"
+        end
+
+        actual_custom_field_values_gids = [enum_value.fetch('gid')]
+      end
+      actual_custom_field_values_gids
+    end
+  end
+
+  # Evaluator task selectors against a task
+  class TaskSelectorEvaluator
+    def initialize(task:)
+      @task = task
+    end
+
+    FUNCTION_EVALUTORS = [
+      NotFunctionEvaluator,
+      NilPFunctionEvaluator,
+      TagPFunctionEvaluator,
+      CustomFieldValueFunctionEvaluator,
+      CustomFieldGidValueContainsAnyGidFunctionEvaluator,
+    ].freeze
+
+    def evaluate(task_selector)
+      return true if task_selector == []
+
+      FUNCTION_EVALUTORS.each do |evaluator_class|
+        evaluator = evaluator_class.new(task_selector: task_selector)
+
+        next unless evaluator.matches?
+
+        return try_this_evaluator(task_selector, evaluator)
+      end
+
+      raise "Syntax issue trying to handle #{task_selector}"
+    end
+
+    private
+
+    def try_this_evaluator(task_selector, evaluator)
+      evaluated_args = task_selector[1..].map.with_index do |item, index|
+        if evaluator.evaluate_arg?(index)
+          evaluate(item)
+        else
+          item
+        end
+      end
+
+      evaluator.evaluate(task, *evaluated_args)
+    end
+
+    attr_reader :task, :task_selector
+  end
+end

data/lib/checkoff/my_tasks.rb

@@ -14,7 +14,7 @@ module Checkoff
 
     attr_reader :projects
 
-    def initialize(config: Checkoff::ConfigLoader.load(:asana),
+    def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    projects: Checkoff::Projects.new(config: config))
       @config = config
       @projects = projects

data/lib/checkoff/projects.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'config_loader'
+require_relative 'internal/config_loader'
 require_relative 'workspaces'
 require_relative 'clients'
 require 'cache_method'
@@ -23,7 +23,7 @@ module Checkoff
     LONG_CACHE_TIME = MINUTE * 15
     SHORT_CACHE_TIME = MINUTE * 5
 
-    def initialize(config: Checkoff::ConfigLoader.load(:asana),
+    def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    workspaces: Checkoff::Workspaces.new(config: config),
                    clients: Checkoff::Clients.new(config: config),
                    client: clients.client)

data/lib/checkoff/sections.rb

@@ -17,7 +17,7 @@ module Checkoff
 
     attr_reader :projects, :workspaces, :time, :my_tasks
 
-    def initialize(config: Checkoff::ConfigLoader.load(:asana),
+    def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    projects: Checkoff::Projects.new(config: config),
                    workspaces: Checkoff::Workspaces.new(config: config),
                    clients: Checkoff::Clients.new(config: config),

data/lib/checkoff/subtasks.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'forwardable'
-require_relative 'config_loader'
+require_relative 'internal/config_loader'
 require_relative 'projects'
 
 module Checkoff
@@ -13,7 +13,7 @@ module Checkoff
 
     extend Forwardable
 
-    def initialize(config: Checkoff::ConfigLoader.load(:asana),
+    def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    projects: Checkoff::Projects.new(config: config))
       @projects = projects
     end

data/lib/checkoff/tags.rb

@@ -4,7 +4,7 @@
 
 require 'forwardable'
 require 'cache_method'
-require_relative 'config_loader'
+require_relative 'internal/config_loader'
 require_relative 'workspaces'
 require_relative 'clients'
 
@@ -20,7 +20,7 @@ module Checkoff
     LONG_CACHE_TIME = MINUTE * 15
     SHORT_CACHE_TIME = MINUTE
 
-    def initialize(config: Checkoff::ConfigLoader.load(:asana),
+    def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    workspaces: Checkoff::Workspaces.new(config: config),
                    clients: Checkoff::Clients.new(config: config),
                    client: clients.client)

data/lib/checkoff/task_searches.rb

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'cache_method'
+require_relative 'internal/config_loader'
+require_relative 'workspaces'
+require_relative 'projects'
+require_relative 'clients'
+require_relative 'task_selectors'
+require 'asana/resource_includes/collection'
+require 'asana/resource_includes/response_helper'
+
+require 'checkoff/internal/search_url_parser'
+
+# https://developers.asana.com/docs/task-searches
+module Checkoff
+  # Run task searches against the Asana API
+  class TaskSearches
+    MINUTE = 60
+    HOUR = MINUTE * 60
+    DAY = 24 * HOUR
+    REALLY_LONG_CACHE_TIME = HOUR * 1
+    LONG_CACHE_TIME = MINUTE * 15
+    SHORT_CACHE_TIME = MINUTE
+
+    include Asana::Resources::ResponseHelper
+
+    def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
+                   workspaces: Checkoff::Workspaces.new(config: config),
+                   task_selectors: Checkoff::TaskSelectors.new(config: config),
+                   projects: Checkoff::Projects.new(config: config),
+                   clients: Checkoff::Clients.new(config: config),
+                   client: clients.client,
+                   search_url_parser: Checkoff::Internal::SearchUrlParser.new,
+                   asana_resources_collection_class: Asana::Resources::Collection)
+      @workspaces = workspaces
+      @task_selectors = task_selectors
+      @projects = projects
+      @client = client
+      @search_url_parser = search_url_parser
+      @asana_resources_collection_class = asana_resources_collection_class
+    end
+
+    def task_search(workspace_name, url, extra_fields: [])
+      workspace = workspaces.workspace_or_raise(workspace_name)
+      api_params, task_selector = @search_url_parser.convert_params(url)
+      path = "/workspaces/#{workspace.gid}/tasks/search"
+      options = calculate_api_options(extra_fields)
+      tasks = @asana_resources_collection_class.new(parse(client.get(path,
+                                                                     params: api_params,
+                                                                     options: options)),
+                                                    type: Asana::Resources::Task,
+                                                    client: client)
+      tasks.select { |task| task_selectors.filter_via_task_selector(task, task_selector) }
+    end
+    cache_method :task_search, LONG_CACHE_TIME
+
+    private
+
+    def calculate_api_options(extra_fields)
+      options = projects.task_options[:options]
+      options[:fields] += ['custom_fields']
+      options[:fields] += extra_fields
+      options
+    end
+
+    # bundle exec ./task_searches.rb
+    # :nocov:
+    class << self
+      def run
+        workspace_name = ARGV[0] || raise('Please pass workspace name as first argument')
+        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)
+        puts "Results: #{task_search}"
+      end
+    end
+    # :nocov:
+
+    attr_reader :task_selectors, :projects, :workspaces, :client
+  end
+end
+
+# :nocov:
+abs_program_name = File.expand_path($PROGRAM_NAME)
+Checkoff::TaskSearches.run if abs_program_name == __FILE__
+# :nocov:

data/lib/checkoff/task_selectors.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'cache_method'
+require 'json'
+require_relative 'internal/config_loader'
+require_relative 'internal/task_selector_evaluator'
+
+# https://developers.asana.com/docs/task-selectors
+
+module Checkoff
+  # Filter lists of tasks using declarative selectors.
+  class TaskSelectors
+    MINUTE = 60
+    HOUR = MINUTE * 60
+    DAY = 24 * HOUR
+    REALLY_LONG_CACHE_TIME = HOUR * 1
+    LONG_CACHE_TIME = MINUTE * 15
+    SHORT_CACHE_TIME = MINUTE
+
+    def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana))
+      @config = config
+    end
+
+    # @param [Hash<Symbol, Object>] task_selector Filter based on
+    #        description.  Examples: {tag: 'foo'} {:not {tag: 'foo'} (:tag 'foo')
+    def filter_via_task_selector(task, task_selector)
+      evaluator = TaskSelectorEvaluator.new(task: task)
+      evaluator.evaluate(task_selector)
+    end
+
+    # bundle exec ./task_selectors.rb
+    # :nocov:
+    class << self
+      def project_name
+        ARGV[1] || raise('Please pass project name to pull tasks from as first argument')
+      end
+
+      def workspace_name
+        ARGV[0] || raise('Please pass workspace name as first argument')
+      end
+
+      def task_selector
+        task_selector_json = ARGV[2] || raise('Please pass task_selector in JSON form as third argument')
+        JSON.parse(task_selector_json)
+      end
+
+      def run
+        require 'checkoff/projects'
+
+        task_selectors = Checkoff::TaskSelectors.new
+        extra_fields = ['custom_fields']
+        projects = Checkoff::Projects.new
+        project = projects.project_or_raise(workspace_name, project_name)
+        raw_tasks = projects.tasks_from_project(project, extra_fields: extra_fields)
+        tasks = raw_tasks.filter { |task| task_selectors.filter_via_task_selector(task, task_selector) }
+        # avoid n+1 queries generating the full task formatting
+        puts JSON.pretty_generate(tasks.map(&:to_h))
+      end
+    end
+    # :nocov:
+  end
+end
+
+# :nocov:
+abs_program_name = File.expand_path($PROGRAM_NAME)
+Checkoff::TaskSelectors.run if abs_program_name == __FILE__
+# :nocov:

data/lib/checkoff/tasks.rb

@@ -14,7 +14,7 @@ module Checkoff
     LONG_CACHE_TIME = MINUTE * 15
     SHORT_CACHE_TIME = MINUTE * 5
 
-    def initialize(config: Checkoff::ConfigLoader.load(:asana),
+    def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    sections: Checkoff::Sections.new(config: config),
                    clients: Checkoff::Clients.new(config: config),
                    client: clients.client,

data/lib/checkoff/version.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
+# Command-line and gem client for Asana (unofficial)
 module Checkoff
   # Version of library
-  VERSION = '0.17.0'
+  VERSION = '0.19.0'
 end

data/lib/checkoff/workspaces.rb

@@ -2,7 +2,7 @@
 
 require 'forwardable'
 require 'cache_method'
-require_relative 'config_loader'
+require_relative 'internal/config_loader'
 require_relative 'clients'
 
 # https://developers.asana.com/docs/workspaces
@@ -17,7 +17,7 @@ module Checkoff
     LONG_CACHE_TIME = MINUTE * 15
     SHORT_CACHE_TIME = MINUTE
 
-    def initialize(config: Checkoff::ConfigLoader.load(:asana),
+    def initialize(config: Checkoff::Internal::ConfigLoader.load(:asana),
                    clients: Checkoff::Clients.new(config: config),
                    client: clients.client)
       @config = config

data/lib/checkoff.rb

@@ -8,3 +8,4 @@ require 'checkoff/subtasks'
 require 'checkoff/tasks'
 require 'checkoff/custom_fields'
 require 'checkoff/tags'
+require 'checkoff/task_selectors'

data/rakelib/console.rake

@@ -2,5 +2,14 @@
 
 desc 'Load up checkoff in pry'
 task :console do |_t|
+  puts 'Example:'
+  puts
+  puts '# https://www.rubydoc.info/github/Asana/ruby-asana/master'
+  puts '> client = Checkoff::Clients.new.client'
+  puts '# https://developers.asana.com/docs/input-output-options'
+  puts '> workspace_gid = ENV.fetch("ASANA__DEFAULT_WORKSPACE_GID")'
+  puts "> task = client.tasks.find_by_id('1199961990964812', options: { fields: ['dependencies'] })"
+  puts '# Asana.md#ruby-asana / API shows how to manually call endpoints with a client'
+  puts
   exec 'pry -I lib -r checkoff'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: checkoff
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.19.0
 platform: ruby
 authors:
 - Vince Broz
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-05-07 00:00:00.000000000 Z
+date: 2022-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -108,6 +108,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: mdl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest-profile
   requirement: !ruby/object:Gem::Requirement
@@ -275,10 +289,13 @@ files:
 - ".git-hooks/pre_commit/circle_ci.rb"
 - ".gitattributes"
 - ".gitignore"
+- ".markdownlint_style.rb"
+- ".mdlrc"
 - ".overcommit.yml"
 - ".rubocop.yml"
 - ".yamllint.yml"
 - CODE_OF_CONDUCT.md
+- CONTRIBUTING.rst
 - DEVELOPMENT.md
 - Gemfile
 - Gemfile.lock
@@ -301,14 +318,19 @@ files:
 - lib/checkoff.rb
 - lib/checkoff/cli.rb
 - lib/checkoff/clients.rb
-- lib/checkoff/config_loader.rb
 - lib/checkoff/create-entity.sh
 - lib/checkoff/custom_fields.rb
+- lib/checkoff/internal/config_loader.rb
+- lib/checkoff/internal/create-class.sh
+- lib/checkoff/internal/search_url_parser.rb
+- lib/checkoff/internal/task_selector_evaluator.rb
 - lib/checkoff/my_tasks.rb
 - lib/checkoff/projects.rb
 - lib/checkoff/sections.rb
 - lib/checkoff/subtasks.rb
 - lib/checkoff/tags.rb
+- lib/checkoff/task_searches.rb
+- lib/checkoff/task_selectors.rb
 - lib/checkoff/tasks.rb
 - lib/checkoff/version.rb
 - lib/checkoff/workspaces.rb

data/lib/checkoff/config_loader.rb

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-require 'yaml'
-require 'active_support/core_ext/hash'
-
-module Checkoff
-  # Use the provided config from a YAML file, and fall back to env
-  # variable if it's not populated for a key'
-  class EnvFallbackConfigLoader
-    def initialize(config, sym, yaml_filename)
-      @config = config
-      @envvar_prefix = sym.upcase
-      @yaml_filename = yaml_filename
-    end
-
-    def [](key)
-      config_value = @config[key]
-      return config_value unless config_value.nil?
-
-      ENV[envvar_name(key)]
-    end
-
-    def fetch(key)
-      out = self[key]
-      return out unless out.nil?
-
-      raise KeyError,
-            "Please configure either the #{key} key in #{@yaml_filename} or set #{envvar_name(key)}"
-    end
-
-    private
-
-    def envvar_name(key)
-      "#{@envvar_prefix}__#{key.upcase}"
-    end
-  end
-
-  # Load configuration file
-  class ConfigLoader
-    class << self
-      def load(sym)
-        yaml_result = load_yaml_file(sym)
-        EnvFallbackConfigLoader.new(yaml_result, sym, yaml_filename(sym))
-      end
-
-      private
-
-      def load_yaml_file(sym)
-        filename = yaml_filename(sym)
-        return {} unless File.exist?(filename)
-
-        YAML.load_file(filename).with_indifferent_access
-      end
-
-      def yaml_filename(sym)
-        file = "#{sym}.yml"
-        File.expand_path("~/.#{file}")
-      end
-    end
-  end
-end