slk 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae44e63120d4264c9adeb4adb2ea9aba96c4fe9e6087c1134f9bd9d8480a843e
-  data.tar.gz: '087ea385b7cf62868737d1e583e60ec9fac5aee8bb3d49f711f5c979413db4e7'
+  metadata.gz: eec8154512ee9815597065ac68471bfd2ad55535191d4057e55ae4d942f15f66
+  data.tar.gz: 3fe2bdbe0fa65ce0b0ee4a529531a38c59f78c674eed08f22d5d40b833b79150
 SHA512:
-  metadata.gz: 71be8f27208e35f5dfe81c3504f38f40af7a7630d93802ba56316e07778aa631f7a42ffe1172b9b1c280735871c0667b5b6568a3bb0224642cdabf59523ac8c5
-  data.tar.gz: 9e4b991d52004df5100fe901e87c1b61f8c50a8fa501665f2cb0a5f58f31a37a6ffae6cbe5c287aac7ae2e99f679cea0889c80866f7980b7f495c7311a507c73
+  metadata.gz: e9a595db19f0748ccb42a4ec436dffa0fe4bbb4d1fbff0514f659cee09a8fb1db2c5258cdd7e74252972c2029e63de0082a2cadf33d96f98dff1681717680e88
+  data.tar.gz: 0e33aa2ec6319fe88433dffe30865d0c17306da34cf136aebd1e9b17e9bb42d9bc5447748914751a74e48f43883bfe3cc404fb657cfaf33c2abdf7db369d2e9a

data/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.0] - 2026-09-18
+
+### Added
+
+- **`slk deactivations --tenure`** — how long each person stayed
+  - Start dates come from the workspace's "Start Date" custom profile field, discovered from the team schema rather than hardcoded, since every workspace numbers its own fields. A date-typed field wins over a text one with the same label
+  - `users.list` does not carry custom fields, so this costs one `users.profile.get` per person, and Slack rate-limits that endpoint to roughly eight calls a minute. The command says how long it will take before it starts, and only looks up the rows it is about to show
+  - Every answer is cached the moment it arrives, not at the end, so 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
+  - Tenure is counted in whole months: somebody who started on the 20th and left on the 3rd has not completed that month. An end date before the start is a data entry error rather than a negative tenure, and reads as blank
+  - Blank means nobody filled the field in, and the column disappears entirely when no start date is known. `--tenure` with `--chart` is refused rather than ignored — a histogram has no row to hang a tenure on
+- **`slk deactivations --csv`** — the spreadsheet that always gets asked for
+  - Writes every match rather than the screenful `-n` would show: a truncated export is a wrong answer that looks like a right one
+  - With `--tenure` it gains `started_on`, `tenure_months` and a readable `tenure` column; unknown start dates leave empty cells rather than zeros, so averaging tenure in a spreadsheet skips them instead of counting people who left the day they arrived
+  - RFC 4180 quoting, hand-rolled, because Ruby 3.4 moved csv out of the default gems and this tool ships with no dependencies
+  - Progress and warnings go to stderr, so `slk deactivations --csv > file.csv` captures only data
+
+### Fixed
+
+- **A cache that cannot be written no longer costs you the run.** `MetaCache.write` returns disk failures instead of raising them: a full or read-only disk means "no cache", not "no answer". This mattered most for start date lookups, which sit behind minutes of rate-limited calls, but it also fixed the deactivation roster scan, which crashed outright on an unwritable cache directory. Other exceptions still raise — a bug in the value being cached is not a disk problem
+- **A cache that cannot be read no longer crashes.** An unreadable cache file now warns and is skipped, the same way a corrupt one already was. The file is left in place rather than deleted, since removing it needs the access that just failed
+- **A malformed API response fails as an API error.** Slack replying with a JSON array, string or null instead of an object used to surface as `TypeError` or `NoMethodError` from whichever command happened to dig into it first
+- **`slk cache clear` now clears all caches.** It removed only the user and channel caches while reporting "Cleared all caches"; start dates, deactivation rosters and resolved profiles survived it
+
+## [0.9.0] - 2026-09-18
+
+### Added
+
+- **`slk deactivations`** — who left the workspace, and when
+  - Slack has no "who left" endpoint. It does have `users.list`, which returns departed accounts with `deleted: true` and an `updated` epoch for the last change to the account — and for a deactivated account that change is almost always the deactivation itself. The help text says so out loud, because an admin who edits a departed profile afterwards moves the date forward, and a date that looks authoritative but is not should say which it is
+  - Defaults to the 25 most recent departures, one per line with a full ISO date, so the output stays greppable. `-n 0` shows all of them
+  - `slk deactivations 90d` (or `--since 90d`, `--since 2026-01-01`) narrows to a window; `--grep` filters across name, handle, title, email and user ID
+  - `--chart` draws departures per calendar month across the whole window asked for, quiet months filled in with zero — a gap in a histogram should read as "nobody left", not as a month that never happened, and a quiet month at either end of the window still happened. Without `--since` it covers the last twelve months rather than the entire history of the workspace
+  - An account Slack never dated cannot answer a question about a window, so it drops out of one — but the footer says how many did, rather than discarding them in silence
+  - Bots and app users are excluded from the counts and the list; `--bots` puts them back
+  - The roster is one API call per 1000 members, so the derived result is cached for six hours. The footer says how old it is, because "nobody left this week" and "nobody left since the last time you asked" are different statements. `--refresh` re-fetches
+
 ## [0.8.0] - 2026-08-30
 
 ### Added

data/README.md

@@ -210,6 +210,73 @@ slk cache populate        # Pre-populate user cache
 slk cache clear           # Clear all caches
 ```
 
+### Deactivations
+
+```bash
+slk deactivations                 # 25 most recent departures
+slk deactivations 90d             # Everyone who left in the last 90 days
+slk deactivations 2026-01-01 -n 0 # All departures this year
+slk deactivations --chart         # Departures per month
+slk deactivations --tenure        # Add how long each person stayed
+slk deactivations 1y --csv        # Spreadsheet export of a year of departures
+slk deactivations --grep engineer # Filter by name, handle, title, email, or ID
+slk deactivations --bots          # Include deactivated bots and app users
+slk deactivations --json          # Machine-readable output
+```
+
+```
+acme: 16 deactivated since 30d (664 active members)
+
+2026-09-14  Dana Whitfield          Platform Support
+2026-09-11  Priya Raghunathan       UX Researcher
+2026-09-09  Sam Okonkwo             Senior Software Engineer
+
+roster cached 5m ago; --refresh to update
+```
+
+Dates come from each account's `updated` field — the last change Slack recorded
+for that user. For a deactivated account that change is almost always the
+deactivation, but an admin editing a departed profile afterwards moves the date
+forward, so treat it as "last touched" rather than a payroll record.
+
+The roster costs one API call per 1000 members, so the result is cached for six
+hours; `--refresh` re-fetches it.
+
+#### Tenure
+
+`--tenure` adds how long each person was here, taken from the workspace's
+"Start Date" profile field:
+
+```
+acme: 3 deactivated since 30d (664 active members)
+
+2026-09-14  Dana Whitfield         1mo  Platform Support
+2026-09-11  Priya Raghunathan   2y 7mo  UX Researcher
+2026-09-09  Sam Okonkwo        4y 10mo  Senior Software Engineer
+```
+
+This one is slow the first time. Start dates are not in the roster — they cost
+one `users.profile.get` per person, and Slack rate-limits that endpoint to
+roughly eight calls a minute, so a screenful takes about three minutes. The
+command says so before it starts, only looks up the rows it is about to show,
+and caches each answer the moment it arrives: interrupting it keeps the work
+already paid for, and the second run is instant.
+
+Blank means nobody filled the field in. Months are whole months, so somebody
+who started on the 20th and left on the 3rd has not completed that month.
+
+#### CSV
+
+`--csv` writes every match — not just the screenful `-n` would show, since a
+truncated export is a wrong answer that looks like a right one. Combine it with
+`--tenure` for `started_on`, `tenure_months` and a readable `tenure` column:
+
+```bash
+slk deactivations 1y --tenure --csv > departures.csv
+```
+
+Progress and warnings go to stderr, so the redirect above captures only data.
+
 ### Global Options
 
 ```bash

data/lib/slk/api/users.rb

@@ -3,6 +3,7 @@
 module Slk
   module Api
     # Wrapper for Slack users.* API endpoints
+    # rubocop:disable Metrics/ClassLength
     class Users
       def initialize(api_client, workspace, on_debug: nil)
         @api = api_client
@@ -63,6 +64,31 @@ module Slk
         @api.post(@workspace, 'users.list', params)
       end
 
+      # Page through users.list until the cursor runs out. Yields the running
+      # total after each page, for progress and debug output.
+      def list_all(limit: 1000, &progress)
+        members = []
+        cursor = nil
+        loop do
+          response = list(cursor: cursor, limit: limit)
+          members.concat(response['members'] || [])
+          progress&.call(members.size)
+          cursor = next_cursor(response, cursor)
+          break members unless cursor
+        end
+      end
+
+      # Slack ends the roster with an empty cursor. A cursor that comes back
+      # unchanged never will, and paging on it spins forever against a remote
+      # API — better to fail with the reason than to hang holding a terminal.
+      def next_cursor(response, previous)
+        cursor = response.dig('response_metadata', 'next_cursor').to_s
+        return nil if cursor.empty?
+        raise ApiError.new('users.list returned a repeating cursor', code: :invalid_cursor) if cursor == previous
+
+        cursor
+      end
+
       def info(user_id)
         @api.post_form(@workspace, 'users.info', { user: user_id })
       end
@@ -111,5 +137,6 @@ module Slk
         @api.post_form(@workspace, 'users.conversations', params)
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/slk/cli.rb

@@ -23,7 +23,8 @@ module Slk
       'help' => Commands::Help,
       'debug' => Commands::Debug,
       'who' => Commands::Who,
-      'org' => Commands::Org
+      'org' => Commands::Org,
+      'deactivations' => Commands::Deactivations
     }.freeze
 
     def initialize(argv, output: nil)

data/lib/slk/commands/cache.rb

@@ -65,6 +65,14 @@ module Slk
         0
       end
 
+      # Every kind, including the meta cache behind start dates, deactivation
+      # rosters and resolved profiles — "cleared" should not have exceptions.
+      def clear_every_cache(workspace_name)
+        cache_store.clear_user_cache(*[workspace_name].compact)
+        cache_store.clear_channel_cache(*[workspace_name].compact)
+        cache_store.clear_meta_cache(*[workspace_name].compact)
+      end
+
       def display_workspace_status(workspace)
         puts output.bold(workspace.name) if target_workspaces.size > 1
         display_cache_counts(workspace)
@@ -87,15 +95,8 @@ module Slk
       end
 
       def clear_cache(workspace_name)
-        if workspace_name
-          cache_store.clear_user_cache(workspace_name)
-          cache_store.clear_channel_cache(workspace_name)
-          success("Cleared cache for #{workspace_name}")
-        else
-          cache_store.clear_user_cache
-          cache_store.clear_channel_cache
-          success('Cleared all caches')
-        end
+        clear_every_cache(workspace_name)
+        success(workspace_name ? "Cleared cache for #{workspace_name}" : 'Cleared all caches')
 
         0
       end

data/lib/slk/commands/deactivations.rb

@@ -0,0 +1,415 @@
+# frozen_string_literal: true
+
+module Slk
+  module Commands
+    # Show who left the workspace and when, derived from users.list.
+    # Examples:
+    #   slk deactivations                 # 25 most recent departures
+    #   slk deactivations 90d             # everyone who left in the last 90 days
+    #   slk deactivations --chart         # departures per month
+    #   slk deactivations --grep engineer # filter by name, handle, title, email, ID
+    #   slk deactivations --tenure        # add how long each person stayed
+    #   slk deactivations --csv           # spreadsheet export of every match
+    # rubocop:disable Metrics/ClassLength
+    class Deactivations < Base
+      DEFAULT_LIMIT = 25
+      CHART_MONTHS = 12
+      # Measured against a live workspace: users.profile.get answers two or
+      # three calls in a row, then makes you wait out a thirty second
+      # Retry-After — about eight lookups a minute averaged over a long run,
+      # which is what the time estimate is built on.
+      LOOKUPS_PER_MINUTE = 8
+      COST_WARNING_AT = 5
+      SWITCHES = {
+        '--chart' => :chart, '--bots' => :bots, '--tenure' => :tenure, '--csv' => :csv,
+        '--refresh' => :refresh, '--no-cache' => :refresh
+      }.freeze
+
+      def execute
+        result = validate_options
+        return result if result
+
+        run
+      rescue Services::StartDateLookup::MissingFieldError => e
+        error(e.message)
+        1
+      rescue ApiError => e
+        error("API error: #{e.message}")
+        1
+      end
+
+      protected
+
+      def handle_option(arg, args, _remaining)
+        return switch_on(SWITCHES[arg]) if SWITCHES.key?(arg)
+
+        case arg
+        when '-n', '--limit' then @options[:limit] = parse_limit(arg, option_value(arg, args))
+        when '--since' then @options[:since] = option_value(arg, args)
+        when '--grep' then @options[:grep] = option_value(arg, args)
+        else return super
+        end
+        true
+      end
+
+      def switch_on(key)
+        @options[key] = true
+      end
+
+      def help_text
+        help = Support::HelpFormatter.new('slk deactivations [since] [options]')
+        help.description('Show deactivated accounts — who left the workspace, and when.')
+        help.note("Dates come from each account's `updated` field, which for a deactivated")
+        help.note('account is the deactivation itself unless an admin edited the profile after.')
+        add_options_section(help)
+        add_examples_section(help)
+        help.render
+      end
+
+      private
+
+      # Base defaults to 72 columns for prose wrapping; this is a table, so use
+      # the whole terminal and let long titles keep their tail. A tty that
+      # refuses to report its size (some Windows consoles, some CI shims) is
+      # not a reason to fail before the command has even parsed its arguments.
+      def default_width
+        return 100 unless $stdout.tty?
+
+        IO.console&.winsize&.last || 100
+      rescue Errno::ENOTTY, Errno::EINVAL, Errno::ENODEV, IOError, NotImplementedError
+        100
+      end
+
+      # `-n foo` used to reach to_i, become 0, and quietly mean "no limit" —
+      # the opposite of asking for fewer rows.
+      def parse_limit(flag, value)
+        limit = Integer(value, exception: false)
+        return limit if limit && !limit.negative?
+
+        raise UsageError, "#{flag} expects a non-negative integer (got #{value.inspect})."
+      end
+
+      def add_options_section(help)
+        help.section('OPTIONS') do |s|
+          s.option('-n, --limit N', "Rows to show (default #{DEFAULT_LIMIT}, 0 for all)")
+          s.option('--since SPEC', 'Only departures since 7d, 4w, 6m, or YYYY-MM-DD')
+          s.option('--chart', 'Histogram of departures per month')
+          s.option('--tenure', 'Add how long each person stayed (slow: one lookup per person)')
+          s.option('--grep PATTERN', 'Filter by name, handle, title, email, or user ID')
+          s.option('--bots', 'Include deactivated bots and app users')
+          add_output_options(s)
+        end
+      end
+
+      def add_output_options(section)
+        section.option('--refresh', 'Re-fetch the roster instead of using the cache')
+        section.option('--csv', 'CSV of every match, for a spreadsheet')
+        section.option('--json', 'Raw JSON output')
+      end
+
+      def add_examples_section(help)
+        help.section('EXAMPLES') do |s|
+          s.example('slk deactivations', 'Most recent departures')
+          s.example('slk deactivations 90d', 'Everyone who left in the last 90 days')
+          s.example('slk deactivations --chart', 'Departures per month')
+          s.example('slk deactivations --tenure', 'How long each person stayed')
+          s.example('slk deactivations 1y --csv > left.csv', 'Export a year of departures')
+          s.example('slk deactivations 2026-01-01 -n 0', 'All departures this year')
+        end
+      end
+
+      def run
+        workspace = runner.workspace(@options[:workspace])
+        validate_combination
+        @since_label = since_spec
+        @since = parse_since(@since_label)
+        report = scan(workspace)
+        records = collect_records(report)
+
+        emit(workspace, report, records)
+        0
+      end
+
+      # --csv and --json export every match; the terminal list is the only
+      # view that pages, so it is the only one -n applies to. (--chart spans
+      # its whole window too, for the same reason.)
+      def emit(workspace, report, records)
+        return render_csv(workspace, records) if @options[:csv]
+        return render_json(workspace, report, records) if @options[:json]
+
+        render(workspace, report, records)
+      end
+
+      # One window, or none. A second date is a different question, and
+      # answering the first one silently is how you misread the answer.
+      def since_spec
+        extra = positional_args[1..]
+        raise UsageError, "Unexpected argument: #{extra.first}. Only one time window is accepted." if extra&.any?
+
+        @options[:since] || positional_args.first
+      end
+
+      # A histogram counts departures per month; it has no row to hang a
+      # tenure on. Refusing beats quietly ignoring the flag someone paid
+      # attention to type.
+      # Two ways of asking for the same rows is one too many, and picking a
+      # winner silently means the other flag looks broken.
+      def validate_combination
+        raise UsageError, '--tenure has nothing to add to --chart; drop one of them.' if
+          @options[:tenure] && @options[:chart]
+        raise UsageError, '--csv and --json are two different exports; pick one.' if
+          @options[:csv] && @options[:json]
+      end
+
+      def collect_records(report)
+        records = filter(report.records)
+        @options[:chart] && @since.nil? ? last_year(records) : records
+      end
+
+      def render_json(workspace, report, records)
+        output_json(json_payload(workspace, report, records, tenures(workspace, records)))
+        0
+      end
+
+      def render_csv(workspace, records)
+        Formatters::DeactivationCsv.new(
+          output: output, tenures: @options[:tenure] ? tenures(workspace, records) : nil
+        ).render(records)
+        0
+      end
+
+      # Start dates cost one rate-limited call each, so they are only ever
+      # fetched for rows that will actually be shown. The caller has already
+      # applied -n (or deliberately not, for an export); this memo assumes one
+      # record set per run, which is what a single command does.
+      def tenures(workspace, records)
+        return {} unless @options[:tenure]
+
+        @tenures ||= resolve_tenures(workspace, records)
+      end
+
+      def resolve_tenures(workspace, records)
+        lookup = start_date_lookup(workspace)
+        announce_cost(lookup, records)
+        dates = begin
+          lookup.fetch(records.map(&:user_id))
+        ensure
+          # Even when the lookup raises: otherwise the error message arrives
+          # glued to a half-drawn "start dates: 12/40".
+          output.clear_progress
+        end
+        report_cache_error(lookup)
+        records.to_h { |r| [r.user_id, Models::Tenure.build(dates[r.user_id], r.deactivated_time)] }
+      end
+
+      # The answers still arrived; they just will not be there next time.
+      def report_cache_error(lookup)
+        return unless lookup.cache_error
+
+        warn("Could not save the start date cache (#{lookup.cache_error}). " \
+             'These lookups will have to be repeated next run.')
+      end
+
+      def start_date_lookup(workspace)
+        Services::StartDateLookup.new(
+          users_api: runner.users_api(workspace.name),
+          field: start_date_field(workspace),
+          workspace_name: workspace.name,
+          cache_store: cache_store,
+          on_progress: ->(done, total) { output.progress("start dates: #{done}/#{total}") }
+        )
+      end
+
+      def start_date_field(workspace)
+        Services::StartDateField.new(
+          team_api: runner.team_api(workspace.name),
+          workspace_name: workspace.name,
+          cache_store: cache_store,
+          on_debug: ->(msg) { output.debug(msg) }
+        )
+      end
+
+      # Better to say how long this will take than to let someone wonder
+      # whether the terminal has hung.
+      def announce_cost(lookup, records)
+        pending = lookup.uncached_count(records.map(&:user_id))
+        return if pending < COST_WARNING_AT
+
+        minutes = [(pending.to_f / LOOKUPS_PER_MINUTE).round, 1].max
+        warn("Looking up #{pending} start dates, one profile call each. Slack rate-limits these " \
+             "to about #{LOOKUPS_PER_MINUTE} a minute, so this will take roughly #{minutes} " \
+             "minute#{'s' if minutes > 1}. Interrupting is safe: each answer is cached as it arrives.")
+      end
+
+      def scan(workspace)
+        Services::DeactivationScanner.new(
+          users_api: runner.users_api(workspace.name),
+          workspace_name: workspace.name,
+          cache_store: cache_store,
+          on_debug: ->(msg) { output.debug(msg) }
+        ).scan(refresh: @options[:refresh])
+      end
+
+      # Filters compose: --bots, --since, --grep all narrow the same list.
+      # Records Slack never dated cannot answer a question about a window, so
+      # they drop out of one — but they are counted, not silently discarded.
+      def filter(records)
+        records = records.reject(&:bot) unless @options[:bots]
+        pattern = grep_pattern
+        records = records.select { |r| r.matches?(pattern) } if pattern
+        @undated = records.count { |r| r.deactivated_at.nil? }
+        reject_before(records, @since)
+      end
+
+      def reject_before(records, cutoff)
+        return records unless cutoff
+
+        records.select { |r| r.deactivated_at && r.deactivated_at >= cutoff }
+      end
+
+      # An all-time histogram of a decade-old workspace is mostly scrollback.
+      # Counting in months rather than in 31-day steps keeps the window exactly
+      # as long as the label claims.
+      def last_year(records)
+        reject_before(records, last_year_cutoff)
+      end
+
+      def last_year_cutoff
+        now = Time.now
+        index = (now.year * 12) + (now.month - 1) - (CHART_MONTHS - 1)
+        Time.new(index / 12, (index % 12) + 1, 1).to_i
+      end
+
+      # The chart spans the window that was asked for, not merely the months
+      # that happen to contain a departure: a quiet opening month is the
+      # answer to "how bad is it lately", and dropping it flatters the trend.
+      def chart_bounds
+        {
+          from: Time.at(@since || last_year_cutoff).strftime('%Y-%m'),
+          to: Time.now.strftime('%Y-%m')
+        }
+      end
+
+      def parse_since(spec)
+        return nil unless spec
+
+        Support::DateParser.parse(spec)
+      rescue ArgumentError => e
+        raise UsageError, e.message
+      end
+
+      def grep_pattern
+        return nil unless @options[:grep]
+
+        Regexp.new(@options[:grep], Regexp::IGNORECASE)
+      rescue RegexpError => e
+        raise UsageError, "Invalid --grep pattern: #{e.message}"
+      end
+
+      def render(workspace, report, records)
+        formatter = Formatters::DeactivationFormatter.new(output: output, width: @options[:width])
+        formatter.summary(summary_line(workspace, report, records))
+        render_body(formatter, workspace, records)
+        footer = footer(report, records)
+        return if footer.empty?
+
+        puts
+        formatter.note(footer)
+      end
+
+      # Even an empty result keeps its footer: "nobody matched" is worth much
+      # less without how old the roster behind it is.
+      def render_body(formatter, workspace, records)
+        return info('No deactivations match.') if records.empty?
+
+        puts
+        return formatter.chart(records, **chart_bounds) if @options[:chart]
+
+        render_list(formatter, workspace, records)
+      end
+
+      def render_list(formatter, workspace, records)
+        limit = @options[:limit] || DEFAULT_LIMIT
+        shown = limit.positive? ? records.first(limit) : records
+        formatter.list(shown, tenures: tenures(workspace, shown))
+        return unless shown.size < records.size
+
+        puts
+        formatter.note("Showing #{shown.size} of #{records.size} — use -n 0 to see them all.")
+      end
+
+      def summary_line(workspace, report, records)
+        "#{workspace.name}: #{records.size} #{scope_phrase} " \
+          "(#{report.active_count} active members)"
+      end
+
+      def scope_phrase
+        return "deactivated since #{@since_label}" if @since_label
+
+        @options[:chart] ? "deactivated in the last #{CHART_MONTHS} months" : 'deactivated accounts'
+      end
+
+      def footer(report, records)
+        total = total_deactivated(report)
+        age = cache_age(report)
+        parts = []
+        parts << "#{total} deactivated in all (of #{report.human_count} accounts ever created)" if records.size < total
+        parts << undated_note if undated_note
+        parts << "roster cached #{age} ago; --refresh to update" if age
+        parts.join(' · ')
+      end
+
+      # Only worth saying when a window was applied: without one nothing was
+      # dropped for want of a date.
+      def undated_note
+        return nil unless windowed? && @undated.to_i.positive?
+
+        "#{@undated} with no recorded date omitted"
+      end
+
+      def windowed?
+        !@since.nil? || @options[:chart]
+      end
+
+      def total_deactivated(report)
+        return report.deactivated_count if @options[:bots]
+
+        report.records.count { |r| !r.bot }
+      end
+
+      def cache_age(report)
+        return nil unless report.fetched_at
+
+        seconds = Time.now.to_i - report.fetched_at
+        return nil if seconds < 60
+
+        Models::Duration.new(seconds: seconds).to_s
+      end
+
+      def json_payload(workspace, report, records, tenures = {})
+        {
+          workspace: workspace.name,
+          fetched_at: report.fetched_at,
+          active_members: report.active_count,
+          accounts_ever: report.human_count,
+          total_deactivated: total_deactivated(report),
+          includes_bots: @options[:bots] ? true : false,
+          matched: records.size,
+          deactivations: records.map { |r| json_entry(r, tenures) }
+        }
+      end
+
+      # started_on and tenure_months appear only when they were asked for:
+      # a null that means "not looked up" is indistinguishable from one that
+      # means "nobody filled it in".
+      def json_entry(record, tenures)
+        entry = record.to_h.merge(deactivated_on: record.date)
+        return entry unless @options[:tenure]
+
+        tenure = tenures[record.user_id]
+        entry.merge(started_on: tenure&.started, tenure_months: tenure&.months)
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end