snitcher_reports 0.2.0

data/lib/snitcher/presenters/presenter.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Snitcher
+  module Presenters
+    module Presenter
+      include TimeFormatter
+
+      TITLE_TRUNCATE_LENGTH = 50
+      TITLE_TRUNCATE_LENGTH_BY_SOURCE = 60
+
+      def self.included(base)
+        base.class_eval do
+          private
+
+          attr_reader :items, :config
+        end
+      end
+
+      def initialize(items, config = {})
+        @items = items
+        @config = config
+      end
+
+      private
+
+      # Tracked work time only — meetings are reported separately (see #meetings_total_seconds).
+      def total_seconds
+        MeetingsAggregator.non_meeting_items(items).sum { |i| i.time_spent_seconds || 0 }
+      end
+
+      def meetings_total_seconds
+        MeetingsAggregator.total_seconds(items)
+      end
+
+      # Detected anomalies, computed once by Report and passed through config.
+      def anomalies
+        config[:anomalies] || []
+      end
+
+      def truncate(str, length)
+        return str if str.nil? || str.length <= length
+
+        "#{str[0, length - 3]}..."
+      end
+
+      # Build an aligned pipe-delimited table from headers and row data.
+      # Computes max width per column and pads cells accordingly.
+      #
+      # @param headers [Array<String>] column header labels
+      # @param rows [Array<Array<String>>] data rows (each an array of cell strings)
+      # @return [String] the formatted table
+      def format_table(headers, rows)
+        col_widths = headers.map(&:length)
+        rows.each do |row|
+          row.each_with_index do |cell, i|
+            len = cell.to_s.length
+            col_widths[i] = len if col_widths[i] && len > col_widths[i]
+          end
+        end
+
+        lines = []
+        lines << format_table_row(headers, col_widths)
+        lines << "| #{col_widths.map { |w| '-' * w }.join(' | ')} |"
+        rows.each { |row| lines << format_table_row(row, col_widths) }
+        lines.join("\n")
+      end
+
+      # Format a single table row with padded cells.
+      #
+      # @param cells [Array<String>] cell values for the row
+      # @param col_widths [Array<Integer>] column widths to pad to
+      # @return [String] a pipe-delimited, padded row string
+      def format_table_row(cells, col_widths)
+        padded = col_widths.map.with_index do |width, i|
+          cells[i].to_s.ljust(width)
+        end
+        "| #{padded.join(' | ')} |"
+      end
+
+      # Escape a value for safe embedding in a markdown table cell.
+      # Strips newlines/carriage returns and escapes pipes, HTML tags,
+      # and markdown link/image syntax characters.
+      def escape_md(str)
+        return str if str.nil?
+
+        str.to_s.gsub(/[\r\n]+/, ' ').gsub(/[|<>\[\]!`]/) { |c| "\\#{c}" }
+      end
+    end
+  end
+end

data/lib/snitcher/report.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Snitcher
+  class Report
+    PRESENTER_MAP = {
+      markdown: Presenters::Markdown,
+      html: Presenters::Html
+    }.freeze
+
+    # Every format #render accepts, in two kinds: :hash is the data a caller computes
+    # with; the presenter formats are documents a person reads, which ReportService
+    # writes to disk (see ReportWriter). A caller that wants JSON serializes the payload
+    # itself — one to_json call, and the choice of serializer stays with the host.
+    FORMATS = (%i[hash] + PRESENTER_MAP.keys).freeze
+
+    # Lets a caller reject a bad format before doing the expensive fetch, rather than
+    # discovering it once every source has already been queried.
+    def self.supported_format?(format) = FORMATS.include?(format)
+
+    def initialize(items, format: :hash, config: {})
+      @items = items
+      @format = format
+      @config = config
+    end
+
+    # @return [Hash] for :hash, [String] for every other format.
+    def render
+      case @format
+      when :hash then json_payload
+      else presenter_for(@format).render
+      end
+    end
+
+    # Public: the fact payload as a Hash (symbol keys). What :hash renders, and the
+    # value ReportService hands back for every format — a document format adds
+    # metadata[:report_path] to this same Hash.
+    def json_payload
+      {
+        metadata: render_json_metadata,
+        anomalies: anomalies.map(&:to_h),
+        items: @items.map { |item| item_payload(item) },
+        summary: summary_payload
+      }
+    end
+
+    private
+
+    def presenter_for(format)
+      klass = PRESENTER_MAP[format]
+      raise ArgumentError, "Unknown format: #{format}" unless klass
+
+      klass.new(@items, @config.merge(anomalies: anomalies))
+    end
+
+    # Detected anomalies, computed once. Returns empty when anomaly detection is disabled.
+    def anomalies
+      return [] unless @config.fetch(:anomalies_enabled, true)
+
+      @anomalies ||= AnomalyDetector.new(@items, since: @config[:since],
+                                                 until_time: @config[:until_time],
+                                                 working_hours: @config[:working_hours]).detect
+    end
+
+    def render_json_metadata
+      meta = { generated_at: Time.now.iso8601 }
+      meta[:user_email] = @config[:user_email] if @config[:user_email]
+      if @config[:since] && @config[:until_time]
+        meta[:period_from] = @config[:since].strftime('%Y-%m-%d')
+        meta[:period_to] = (@config[:until_time] - TimeFormatter::SECONDS_PER_DAY).strftime('%Y-%m-%d')
+      end
+      # Present only when something went wrong, so a consumer can treat its absence as
+      # "every requested source answered" rather than "this build has no such field".
+      failed = Array(@config[:failed_sources])
+      meta[:failed_sources] = failed.map { |f| { source: f[:source].to_s, error: f[:error].to_s } } if failed.any?
+      meta
+    end
+
+    def item_payload(item)
+      {
+        source: item.source,
+        external_id: item.external_id,
+        title: item.title,
+        completed_at: item.completed_at&.iso8601,
+        time_spent_seconds: item.time_spent_seconds,
+        time_spent_human: item.time_spent_human,
+        url: item.url,
+        metadata: item.metadata
+      }
+    end
+
+    def summary_payload
+      {
+        total_items: @items.count,
+        sources: @items.map(&:source).uniq,
+        # Tracked work time only — meetings are reported separately (see meetings below).
+        total_time_seconds: MeetingsAggregator.non_meeting_items(@items).sum { |i| i.time_spent_seconds || 0 },
+        meetings_total_seconds: meetings_aggregate[:total_seconds],
+        meetings: {
+          total_seconds: meetings_aggregate[:total_seconds],
+          event_count: meetings_aggregate[:event_count],
+          by_series: meetings_aggregate[:rows]
+        }
+      }
+    end
+
+    def meetings_aggregate
+      @meetings_aggregate ||= MeetingsAggregator.aggregate(@items)
+    end
+  end
+end

data/lib/snitcher/report_service.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Snitcher
+  # Turns plain parameters into a rendered report, reusing Orchestrator + Report.
+  # Raises on invalid input (never calls exit) so callers can surface errors.
+  class ReportService
+    SECONDS_PER_DAY = TimeFormatter::SECONDS_PER_DAY
+
+    # Runs one report. Every format returns the fact payload (Hash), with
+    # metadata.report_path set when a document was written.
+    # rubocop:disable-next Metrics/ParameterLists -- keyword args are self-documenting
+    def self.call(from:, user_email: nil, to: nil, sources: nil, include_anomalies: true,
+                  format: :hash, narrative: nil, output_dir: nil, output_path: nil,
+                  orchestrator: nil, configuration: nil)
+      new(configuration: configuration).call(
+        user_email: user_email, from: from, to: to, sources: sources,
+        include_anomalies: include_anomalies, format: format, narrative: narrative,
+        output_dir: output_dir, output_path: output_path, orchestrator: orchestrator
+      )
+    end
+
+    # Coerces a String or Symbol format and rejects anything Report cannot render.
+    # Called before any source is queried, so a typo costs nothing.
+    def self.normalize_format(format)
+      sym = (format || :hash).to_sym
+      unless Report.supported_format?(sym)
+        raise ArgumentError,
+              "Unknown format: #{format}. Available: #{Report::FORMATS.join(', ')}"
+      end
+
+      sym
+    end
+
+    def initialize(configuration: nil)
+      @configuration = configuration || Configuration.new
+    end
+
+    # rubocop:disable Metrics/ParameterLists -- keyword args are self-documenting
+    def call(from:, to:, sources:, include_anomalies:, user_email: nil, format: :hash,
+             narrative: nil, output_dir: nil, output_path: nil, orchestrator: nil)
+      # rubocop:enable Metrics/ParameterLists
+      fmt = self.class.normalize_format(format)
+      since, until_time = parse_date_range(from, to)
+      source_syms = resolve_sources(sources)
+      orch = orchestrator || Orchestrator.new(sources: source_syms, configuration: @configuration)
+      items = orch.fetch(user_email: user_email, since: since, until_time: until_time)
+
+      config = report_config(user_email, since, until_time, include_anomalies,
+                             orch.failed_sources, narrative)
+      report = Report.new(items, format: fmt, config: config)
+      return report.render unless ReportWriter.saved_format?(fmt)
+
+      save(report, fmt, user_email, since, until_time, output_dir, output_path)
+    end
+
+    private
+
+    # Writes the rendered document and hands back the fact payload carrying its location,
+    # so a caller always gets the same Hash to work with whatever format it asked for.
+    # rubocop:disable-next Metrics/ParameterLists -- one argument per filename component
+    def save(report, format, user_email, since, until_time, output_dir, output_path)
+      path = ReportWriter.new(configuration: @configuration, output_dir: output_dir).write(
+        report.render, format: format, user_email: user_email,
+                       since: since, until_time: until_time, output_path: output_path
+      )
+      payload = report.json_payload
+      payload[:metadata][:report_path] = path
+      payload[:metadata][:report_format] = format.to_s
+      payload
+    end
+
+    # Raises on a missing or malformed range instead of exiting.
+    def parse_date_range(from, to)
+      raise ArgumentError, "'from' is required (YYYY-MM-DD)" if from.nil? || from.empty?
+
+      since = parse_date(from)
+      to_str = to.nil? || to.empty? ? Time.now.strftime('%Y-%m-%d') : to
+      until_date = parse_date(to_str)
+      raise ArgumentError, "'from' (#{from}) must not be after 'to' (#{to_str})" unless since <= until_date
+
+      # +1 day so the inclusive 'to' date is fully covered (until_time is exclusive).
+      [since, until_date + SECONDS_PER_DAY]
+    end
+
+    # Wraps only genuine parse failures — keeps guard messages (missing/ordered
+    # dates) intact instead of re-labelling them as "Invalid date".
+    def parse_date(str)
+      Time.parse(str)
+    rescue ArgumentError => e
+      raise ArgumentError, "Invalid date '#{str}': #{e.message}"
+    end
+
+    # Accepts nil, "all", an array, or a comma-separated string. Blank input and an
+    # explicit "all" (in any position) resolve to every source.
+    def resolve_sources(sources)
+      keys = Orchestrator::SOURCE_MAP.keys
+      list = Array(sources).flat_map { |s| s.to_s.split(',') }.map(&:strip).reject(&:empty?)
+      return keys if list.empty? || list.include?('all')
+
+      syms = list.map(&:to_sym)
+      invalid = syms - keys
+      if invalid.any?
+        raise ArgumentError,
+              "Unknown source(s): #{invalid.join(', ')}. Available: #{keys.join(', ')}"
+      end
+
+      syms
+    end
+
+    # Builds the config Hash consumed by Report. narrative is omitted rather than set to
+    # nil, so presenters keep treating "no narrative" as "no Overview section".
+    # rubocop:disable-next Metrics/ParameterLists -- a config builder, one key per argument
+    def report_config(user_email, since, until_time, include_anomalies, failed_sources, narrative)
+      config = {
+        user_email: user_email,
+        since: since,
+        until_time: until_time,
+        working_hours: @configuration.working_hours(user_email: user_email),
+        anomalies_enabled: include_anomalies,
+        failed_sources: failed_sources
+      }
+      config[:narrative] = narrative if narrative
+      config
+    end
+  end
+end

data/lib/snitcher/report_writer.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'pathname'
+
+module Snitcher
+  # Writes a rendered report to disk. Markdown and HTML are documents a person opens, not
+  # values a host program computes with — handing back a multi-kilobyte String and leaving
+  # the host to invent a filename means every host invents a different one. So the gem
+  # writes the file and reports where, and the caller still gets the fact payload.
+  class ReportWriter
+    EXTENSIONS = { markdown: 'md', html: 'html' }.freeze
+
+    # Written to disk instead of returned as a String.
+    SAVED_FORMATS = EXTENSIONS.keys.freeze
+
+    DEFAULT_OUTPUT_DIR = 'snitcher_reports'
+
+    # Stands in for the user in a filename when no email was requested (the "run it for
+    # myself" path, where identity comes from sources.<name>.user).
+    ANONYMOUS_SLUG = 'report'
+
+    def self.saved_format?(format) = SAVED_FORMATS.include?(format)
+
+    def initialize(configuration: nil, output_dir: nil)
+      @configuration = configuration
+      @output_dir = output_dir
+    end
+
+    # Writes content and returns the absolute path it landed at. output_path names the
+    # file outright; otherwise the name is derived from the user and the period, so
+    # regenerating the same report overwrites it rather than piling up copies.
+    # rubocop:disable-next Metrics/ParameterLists -- keyword args are self-documenting
+    def write(content, format:, user_email: nil, since: nil, until_time: nil, output_path: nil)
+      path = Pathname.new(output_path || default_path(format, user_email, since, until_time)).expand_path
+      FileUtils.mkdir_p(path.dirname)
+      path.write(content)
+      path.to_s
+    end
+
+    private
+
+    def default_path(format, user_email, since, until_time)
+      File.join(resolved_output_dir, "#{filename_for(user_email, since, until_time)}.#{EXTENSIONS.fetch(format)}")
+    end
+
+    # Explicit argument, then output_dir from .snitcher.yml, then a directory under the
+    # working directory — never the working directory itself, which is the host
+    # application's own root and not ours to scatter files across.
+    def resolved_output_dir
+      @output_dir || @configuration&.output_dir || DEFAULT_OUTPUT_DIR
+    end
+
+    def filename_for(user_email, since, until_time)
+      [slugify(user_email), period_slug(since, until_time)].compact.join('_')
+    end
+
+    def period_slug(since, until_time)
+      return nil unless since && until_time
+
+      last_day = until_time - TimeFormatter::SECONDS_PER_DAY
+      "#{since.strftime('%Y-%m-%d')}_#{last_day.strftime('%Y-%m-%d')}"
+    end
+
+    # Keeps the address readable while stripping anything that would nest the file in a
+    # directory or confuse a shell: alice@corp.com => alice-at-corp.com.
+    def slugify(user_email)
+      return ANONYMOUS_SLUG if user_email.nil? || user_email.to_s.strip.empty?
+
+      slug = user_email.to_s.strip.downcase.gsub('@', '-at-').gsub(/[^a-z0-9._-]+/, '-')
+      slug.empty? ? ANONYMOUS_SLUG : slug
+    end
+  end
+end

data/lib/snitcher/sources/clickup/archived_lists.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Snitcher
+  module Sources
+    class ClickUp < Source
+      # Reads the tasks that team/{team_id}/task cannot see: those whose List, Folder or
+      # Space has been archived. ClickUp drops them from that endpoint whatever the
+      # `archived` parameter is set to, so they are reachable only by walking the
+      # hierarchy and asking each List for its tasks.
+      # Depends on constants and helpers defined in ClickUp: PAGINATION_MAX_PAGES,
+      # ARCHIVED_LISTS_MAX, MS_PER_SECOND, #connection, #fetch_spaces, #filter_tasks_by_date.
+      # @api private
+      module ArchivedLists
+        private
+
+        # Tasks from archived Lists for the whole workspace, not for one person: the
+        # orchestrator builds its sources once and walks people sequentially, so a team
+        # report pays for the walk once and each person filters the result with
+        # #assigned_to?. Keyed by the window because Orchestrator#fetch is public and a
+        # host may call it again with a different period.
+        def archived_tasks(since:, until_time:)
+          window = [since.to_i, until_time.to_i]
+          return @archived_tasks if @archived_window == window
+
+          tasks = fetch_archived_list_tasks(since: since, until_time: until_time)
+          @archived_window = window
+          @archived_tasks = filter_tasks_by_date(tasks, since: since, until_time: until_time)
+        end
+
+        def fetch_archived_list_tasks(since:, until_time:)
+          list_ids = archived_list_ids
+          return [] if list_ids.empty?
+
+          errors = []
+          tasks = list_ids.flat_map do |list_id|
+            paginate_list_tasks(list_id: list_id, since: since, until_time: until_time)
+          rescue Faraday::UnauthorizedError, Faraday::ForbiddenError
+            # A revoked token answers every remaining list the same way; degrading past it
+            # would report a quiet quarter instead of an outage.
+            raise
+          rescue Faraday::Error => e
+            errors << e
+            warn "[clickup] Warning: could not read archived list #{list_id} (#{e.message})"
+            []
+          end
+
+          # Keyed on how many lists failed, not on how many tasks came back: most windows
+          # close nothing in an archived list, so one timeout among healthy empty answers
+          # must not fail the source and discard the live pass with it.
+          raise errors.first if errors.size == list_ids.size
+
+          # With "Tasks in Multiple Lists" one task answers from every list it is in.
+          tasks.uniq { |task| task['id'] }
+        end
+
+        def archived_list_ids
+          @archived_list_ids ||= begin
+            ids = archived_lists.filter_map { |list| validated_id(list['id'], name: 'list_id') }
+            if ids.size > ARCHIVED_LISTS_MAX
+              warn "[clickup] Warning: #{ids.size} archived lists found; reading the first " \
+                   "#{ARCHIVED_LISTS_MAX}. Tasks in the rest are missing from this report"
+              ids = ids.first(ARCHIVED_LISTS_MAX)
+            end
+            ids
+          end
+        end
+
+        # Every list found this way is read, including the ones reporting task_count 0:
+        # that count covers open tasks only. A finished sprint reports 0 and still holds
+        # its closed tasks — of twelve such lists sampled on a real workspace, eleven
+        # answered with tasks, sixty of them closed.
+        def archived_lists
+          walk_spaces.flat_map do |space_id, space_archived|
+            archived_lists_in_space(space_id, space_archived: space_archived)
+          end.uniq { |list| list['id'] }
+        end
+
+        # @return [Array<Array(String, Boolean)>] space id and whether the space is archived
+        def walk_spaces
+          # Configured space names resolve against the live enumeration (#resolve_space_ids),
+          # so a configured space is never an archived one. Honouring the setting here also
+          # keeps `spaces:` meaning what it says: the walk stays inside it.
+          return @space_ids.to_a.map { |id| [id, false] } if @space_ids.any?
+
+          spaces = fetch_spaces.map { |space| [space['id'], false] } +
+                   fetch_archived_spaces.map { |space| [space['id'], true] }
+          spaces.filter_map do |raw_id, archived|
+            id = validated_id(raw_id, name: 'space_id')
+            [id, archived] if id
+          end
+        end
+
+        def archived_lists_in_space(space_id, space_archived:)
+          folders = fetch_folders(space_id, archived: false) + fetch_folders(space_id, archived: true)
+          lists = folders.uniq { |folder| folder['id'] }.flat_map do |folder|
+            folder_id = validated_id(folder['id'], name: 'folder_id')
+            next [] unless folder_id
+
+            lists_under("folder/#{folder_id}/list", parent_archived: folder['archived'] || space_archived)
+          end
+          lists + lists_under("space/#{space_id}/list", parent_archived: space_archived)
+        end
+
+        # A List inside an archived Folder or Space usually carries archived: false of its
+        # own — the parent is what was archived — so membership, not the List's own flag,
+        # decides. Reading only the archived enumeration would miss those.
+        def lists_under(path, parent_archived:)
+          fetch_lists(path, archived: true) +
+            (parent_archived ? fetch_lists(path, archived: false) : [])
+        end
+
+        # Subfolders arrive in this same flat list, each carrying a parent_folder id, so
+        # the hierarchy needs no recursion.
+        def fetch_folders(space_id, archived:)
+          connection.get("space/#{space_id}/folder", { archived: archived }).body['folders'] || []
+        end
+
+        def fetch_lists(path, archived:)
+          connection.get(path, { archived: archived }).body['lists'] || []
+        end
+
+        # Mirrors #fetch_spaces for the other half of the enumeration; archived: true
+        # answers with archived spaces only, so the two never overlap.
+        def fetch_archived_spaces
+          @fetch_archived_spaces ||= connection.get("team/#{@team_id}/space", { archived: true })
+                                               .body['spaces'] || []
+        end
+
+        def paginate_list_tasks(list_id:, since:, until_time:)
+          tasks = []
+          page = 0
+
+          loop do
+            response = connection.get("list/#{list_id}/task") do |req|
+              # No `archived` parameter: it filters by the task's own archived flag rather
+              # than its list's, and the same archived list answers with 3 tasks when it is
+              # sent and 8 when it is not. The live pass does not send it either.
+              req.params = {
+                'include_closed' => true,
+                'date_done_gt' => (since.to_f * MS_PER_SECOND).to_i,
+                'date_done_lt' => (until_time.to_f * MS_PER_SECOND).to_i,
+                'page' => page
+              }
+            end
+
+            tasks.concat(response.body['tasks'] || [])
+            # This endpoint reports the end of the listing; team/{team_id}/task does not,
+            # which is why #paginate_tasks has to recognise a repeated page instead.
+            break unless response.body['last_page'] == false
+
+            page += 1
+            break if page >= PAGINATION_MAX_PAGES
+          end
+
+          tasks
+        end
+
+        # team/{team_id}/task?assignees[] matches the assignee field alone, so a task the
+        # person only watches or created has never been in the report. Matching more here
+        # would make a person's report depend on whether the list was archived.
+        def assigned_to?(task, user_id)
+          Array(task['assignees']).any? { |assignee| assignee['id'].to_s == user_id.to_s }
+        end
+
+        def validated_id(raw_id, name:)
+          Validators.validate_id!(raw_id, name: name)
+        rescue Validators::ValidationError => e
+          warn "[clickup] Warning: skipping #{name} (#{e.message})"
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/snitcher/sources/clickup/working_hours_filter.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative '../../working_hours_calculator'
+
+module Snitcher
+  module Sources
+    class ClickUp < Source
+      # Working-hours interval reconstruction for ClickUp's status-time fallback (Tier 3).
+      # Extracted from ClickUp to keep class length under RuboCop's Metrics/ClassLength limit.
+      # Depends on constants defined in ClickUp: CUSTOM_STATUS_TYPE, SECONDS_PER_MINUTE, MS_PER_SECOND.
+      # @api private
+      module WorkingHoursFilter
+        private
+
+        # Returns seconds spent in 'custom' (in-progress) statuses.
+        # With working_hours: reconstructs intervals from `since` timestamps and filters.
+        # Without: fast path using by_minute sum.
+        #
+        # @param status_history [Array<Hash>, nil] status history from time_in_status API
+        # @param task_closed_at [Time, nil] when the task was closed (end bound for last interval)
+        # @return [Integer] seconds spent in in-progress statuses
+        def calculate_time_from_status_history(status_history, task_closed_at: nil)
+          return 0 if status_history.nil? || status_history.empty?
+
+          custom_entries = status_history.select { |s| s['type'] == CUSTOM_STATUS_TYPE }
+          return 0 if custom_entries.empty?
+
+          raw_seconds = [custom_entries.sum { |s| s.dig('total_time', 'by_minute').to_i } * SECONDS_PER_MINUTE, 0].max
+
+          return raw_seconds unless @working_hours
+
+          filtered_seconds = calculate_filtered_status_time(status_history, task_closed_at: task_closed_at)
+          # Cap at raw by_minute; when 0, fall back to raw (ClickUp API limitation:
+          # can't distinguish missing timestamps from all-outside-working-hours).
+          if filtered_seconds.positive?
+            [filtered_seconds, raw_seconds].min
+          else
+            warn '[Snitcher::ClickUp] Working hours filter returned 0; falling back to raw by_minute' if ENV['DEBUG']
+            raw_seconds
+          end
+        end
+
+        # Reconstructs time intervals from status_history since timestamps,
+        # then filters each interval through WorkingHoursCalculator.
+        #
+        # Sort all entries chronologically by `since`, then for each 'custom' entry
+        # its end time is the next entry's `since` (or task_closed_at for the last).
+        #
+        # Limitation: ClickUp returns one entry per unique status (not per transition).
+        # For bouncing tasks, `since` reflects only the last entry — earlier periods are lost.
+        # The caller caps the result at by_minute * SECONDS_PER_MINUTE.
+        #
+        # @param status_history [Array<Hash>] full status history (all types)
+        # @param task_closed_at [Time, nil] task close time (end bound for last interval;
+        #   when nil, last custom interval is silently dropped)
+        # @return [Integer] filtered seconds (0 when no usable since timestamps)
+        # @note Caller must ensure @working_hours is non-nil before calling this method.
+        def calculate_filtered_status_time(status_history, task_closed_at: nil)
+          sorted = status_history
+                   .select { |s| s.dig('total_time', 'since').to_i.positive? }
+                   .sort_by { |s| s.dig('total_time', 'since').to_i }
+
+          return 0 if sorted.empty?
+
+          total = 0
+          sorted.each_with_index do |entry, i|
+            next unless entry['type'] == CUSTOM_STATUS_TYPE
+
+            start_ms = entry.dig('total_time', 'since').to_i
+            start_time = Time.at(start_ms / MS_PER_SECOND)
+
+            next_since_ms = sorted[i + 1]&.dig('total_time', 'since')&.to_i
+            end_time = if next_since_ms&.positive?
+                         Time.at(next_since_ms / MS_PER_SECOND)
+                       else
+                         task_closed_at
+                       end
+
+            next unless end_time && end_time > start_time
+
+            total += WorkingHoursCalculator.seconds_between(start_time, end_time, @working_hours)
+          end
+          total
+        end
+      end
+    end
+  end
+end