slk 0.8.0 → 0.10.0

data/lib/slk/services/start_date_field.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Slk
+  module Services
+    # Which custom profile field holds a start date, if any.
+    #
+    # Workspaces name and number these fields themselves, so the ID has to be
+    # discovered from the team schema rather than hardcoded — and the schema
+    # barely changes, so the answer is cached for a week.
+    class StartDateField
+      CACHE_KEY = 'start_date_field_v1'
+      TTL = 604_800 # 7 days
+      LABEL = /\Astart date\z/i
+
+      def initialize(team_api:, workspace_name:, cache_store: nil, on_debug: nil)
+        @team_api = team_api
+        @workspace_name = workspace_name
+        @cache = cache_store
+        @on_debug = on_debug
+      end
+
+      # @return [String, nil] the Xf… field ID, or nil if the workspace has none
+      def id
+        return @id if defined?(@id)
+
+        cached = MetaCache.read(@cache, @workspace_name, CACHE_KEY, ttl: TTL)
+        @id = cached.is_a?(Hash) ? cached['id'] : discover
+      end
+
+      def missing_message
+        'This workspace has no "Start Date" profile field, so tenure cannot be worked out. ' \
+          'Run `slk debug schema` (an undocumented command) to see the fields it does have.'
+      end
+
+      private
+
+      # A date-typed field wins over a text one with the same label: someone
+      # typing "started summer 2019" into a text box is not a date.
+      def discover
+        id = usable_id(best_match(@team_api.profile_schema.dig('profile', 'fields')))
+        @on_debug&.call("start date field: #{id || 'not found in team schema'}")
+        remember(id)
+        id
+      end
+
+      def usable_id(match)
+        id = match && match['id']
+        id.is_a?(String) && !id.empty? ? id : nil
+      end
+
+      # Losing this costs one extra team.profile.get next run, not minutes of
+      # rate-limited lookups, so it is noted rather than warned about.
+      def remember(id)
+        failure = MetaCache.write(@cache, @workspace_name, CACHE_KEY, { 'id' => id })
+        @on_debug&.call("start date field cache not written: #{failure.message}") if failure
+      end
+
+      # A workspace that answers with something other than a list of field
+      # hashes has no start date field as far as we are concerned — better a
+      # clear "this workspace cannot do tenure" than an unexpected error.
+      def best_match(fields)
+        labelled = Array(fields).grep(Hash).select { |f| LABEL.match?(f['label'].to_s.strip) }
+        labelled.find { |f| f['type'] == 'date' } || labelled.first
+      end
+    end
+  end
+end

data/lib/slk/services/start_date_lookup.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Slk
+  module Services
+    # Start dates live in a workspace custom profile field, which `users.list`
+    # does not return — they cost one `users.profile.get` per person, and Slack
+    # rate-limits that endpoint hard enough that a screenful takes minutes
+    # rather than seconds.
+    #
+    # So every answer is cached, and cached the moment it arrives rather than
+    # at the end: interrupting a long lookup keeps the work already paid for.
+    # Accounts with no start date on file are cached too, otherwise every run
+    # would pay again to learn the same nothing.
+    #
+    # The cache holds for 30 days. A departed account's start date rarely
+    # changes, but an admin correcting a typo in one is exactly the case the
+    # expiry exists for; `slk cache clear` forces the issue sooner.
+    class StartDateLookup
+      CACHE_KEY = 'start_dates_v1'
+      TTL = 2_592_000 # 30 days
+
+      class MissingFieldError < Slk::Error; end
+
+      # Set when the cache could not be written. The lookup carries on — the
+      # cache is an optimisation, and the answers are worth more than it.
+      attr_reader :cache_error
+
+      def initialize(users_api:, field:, workspace_name:, cache_store: nil, on_progress: nil)
+        @users_api = users_api
+        @field = field
+        @workspace_name = workspace_name
+        @cache = cache_store
+        @on_progress = on_progress
+      end
+
+      # @return [Hash{String => String, nil}] user ID => ISO date, or nil for
+      #   an account with no start date recorded
+      def fetch(user_ids)
+        # Checked even for an empty list: "this workspace cannot do tenure" is
+        # the same fact whether or not anyone matched the filter, and finding
+        # out only when someone matches makes it look intermittent.
+        raise MissingFieldError, @field.missing_message if @field.id.to_s.empty?
+        return {} if user_ids.empty?
+
+        known = cached
+        user_ids.each_with_index { |id, index| resolve(known, id, index, user_ids.size) }
+        known.slice(*user_ids)
+      end
+
+      # How many of these would cost an API call, so a caller can warn about
+      # the wait before making someone sit through it.
+      def uncached_count(user_ids)
+        known = cached
+        user_ids.count { |id| !known.key?(id) }
+      end
+
+      private
+
+      def resolve(known, user_id, index, total)
+        return if known.key?(user_id)
+
+        @on_progress&.call(index + 1, total)
+        known[user_id] = start_date_for(user_id)
+        remember(known)
+      end
+
+      # A full or read-only disk must not throw away a lookup that cost
+      # minutes of rate-limited calls. MetaCache.write hands back the failure
+      # instead of raising; the caller reports it once at the end.
+      def remember(known)
+        failure = MetaCache.write(@cache, @workspace_name, CACHE_KEY, known)
+        # First failure only: the same unwritable disk will fail every row.
+        @cache_error = failure.message if failure && @cache_error.nil?
+      end
+
+      # Which account failed matters when the answer arrives twenty rows into
+      # a run that has already taken three minutes.
+      def start_date_for(user_id)
+        fields = @users_api.profile_for(user_id).dig('profile', 'fields')
+        value = fields.is_a?(Hash) ? fields.dig(@field.id, 'value') : nil
+        value.to_s.empty? ? nil : value
+      rescue ApiError => e
+        # Only the plain kind: re-wrapping a RateLimitError would drop its
+        # retry_after and the class the retry logic looks for.
+        raise unless e.instance_of?(ApiError)
+
+        raise ApiError.new("#{e.message} (looking up #{user_id})", code: e.code)
+      end
+
+      def cached
+        @cached ||= begin
+          data = MetaCache.read(@cache, @workspace_name, CACHE_KEY, ttl: TTL)
+          data.is_a?(Hash) ? data : {}
+        end
+      end
+    end
+  end
+end

data/lib/slk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Slk
-  VERSION = '0.8.0'
+  VERSION = '0.10.0'
 end

data/lib/slk.rb

@@ -6,6 +6,7 @@ require 'json'
 require 'fileutils'
 require 'optparse'
 require 'time'
+require 'date'
 require 'io/console'
 
 # Slack CLI - A command-line interface for Slack
@@ -74,6 +75,8 @@ module Slk
     autoload :User, 'slk/models/user'
     autoload :Channel, 'slk/models/channel'
     autoload :Preset, 'slk/models/preset'
+    autoload :Deactivation, 'slk/models/deactivation'
+    autoload :Tenure, 'slk/models/tenure'
     autoload :SearchResult, 'slk/models/search_result'
     autoload :SavedItem, 'slk/models/saved_item'
     autoload :Profile, 'slk/models/profile'
@@ -107,6 +110,9 @@ module Slk
     autoload :ProfileBuilder, 'slk/services/profile_builder'
     autoload :ProfileResolver, 'slk/services/profile_resolver'
     autoload :MetaCache, 'slk/services/meta_cache'
+    autoload :DeactivationScanner, 'slk/services/deactivation_scanner'
+    autoload :StartDateLookup, 'slk/services/start_date_lookup'
+    autoload :StartDateField, 'slk/services/start_date_field'
   end
 
   # Output formatters for messages, durations, and emoji
@@ -129,6 +135,9 @@ module Slk
     autoload :ProfileFormatter, 'slk/formatters/profile_formatter'
     autoload :ProfileFieldRenderer, 'slk/formatters/profile_field_renderer'
     autoload :ProfileRows, 'slk/formatters/profile_rows'
+    autoload :DeactivationFormatter, 'slk/formatters/deactivation_formatter'
+    autoload :DeactivationCsv, 'slk/formatters/deactivation_csv'
+    autoload :CsvWriter, 'slk/formatters/csv_writer'
   end
 
   # CLI commands implementing user-facing functionality
@@ -153,6 +162,7 @@ module Slk
     autoload :Debug, 'slk/commands/debug'
     autoload :Who, 'slk/commands/who'
     autoload :Org, 'slk/commands/org'
+    autoload :Deactivations, 'slk/commands/deactivations'
   end
 
   # Thin wrappers around Slack API endpoints

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slk
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Eric Boehs
@@ -45,6 +45,7 @@ files:
 - lib/slk/commands/cache.rb
 - lib/slk/commands/catchup.rb
 - lib/slk/commands/config.rb
+- lib/slk/commands/deactivations.rb
 - lib/slk/commands/debug.rb
 - lib/slk/commands/dnd.rb
 - lib/slk/commands/emoji.rb
@@ -64,6 +65,9 @@ files:
 - lib/slk/formatters/activity_formatter.rb
 - lib/slk/formatters/attachment_formatter.rb
 - lib/slk/formatters/block_formatter.rb
+- lib/slk/formatters/csv_writer.rb
+- lib/slk/formatters/deactivation_csv.rb
+- lib/slk/formatters/deactivation_formatter.rb
 - lib/slk/formatters/duration_formatter.rb
 - lib/slk/formatters/emoji_replacer.rb
 - lib/slk/formatters/json_message_formatter.rb
@@ -80,6 +84,7 @@ files:
 - lib/slk/formatters/search_formatter.rb
 - lib/slk/formatters/text_processor.rb
 - lib/slk/models/channel.rb
+- lib/slk/models/deactivation.rb
 - lib/slk/models/dnd_state.rb
 - lib/slk/models/duration.rb
 - lib/slk/models/message.rb
@@ -92,6 +97,7 @@ files:
 - lib/slk/models/search_result.rb
 - lib/slk/models/status.rb
 - lib/slk/models/status_snapshot.rb
+- lib/slk/models/tenure.rb
 - lib/slk/models/user.rb
 - lib/slk/models/workspace.rb
 - lib/slk/runner.rb
@@ -99,6 +105,7 @@ files:
 - lib/slk/services/api_client.rb
 - lib/slk/services/cache_store.rb
 - lib/slk/services/configuration.rb
+- lib/slk/services/deactivation_scanner.rb
 - lib/slk/services/emoji_downloader.rb
 - lib/slk/services/emoji_searcher.rb
 - lib/slk/services/encryption.rb
@@ -111,6 +118,8 @@ files:
 - lib/slk/services/profile_resolver.rb
 - lib/slk/services/reaction_enricher.rb
 - lib/slk/services/setup_wizard.rb
+- lib/slk/services/start_date_field.rb
+- lib/slk/services/start_date_lookup.rb
 - lib/slk/services/target_resolver.rb
 - lib/slk/services/token_loader.rb
 - lib/slk/services/token_saver.rb