jirametrics 2.31 → 3.0

data/lib/jirametrics/mcp_server.rb

@@ -65,6 +65,27 @@ class McpServer
     }
   }.freeze
 
+  # Bundles the six history + blocked/stalled query parameters that every tool accepts, so they travel
+  # as one argument instead of a six-long positional tail through matches_history? and the handlers.
+  HistoryFilter = Data.define(
+    :history_field, :history_value, :ever_blocked, :ever_stalled, :currently_blocked, :currently_stalled
+  ) do
+    def self.from(history_field: nil, history_value: nil, ever_blocked: nil, ever_stalled: nil,
+                  currently_blocked: nil, currently_stalled: nil, **)
+      new(
+        history_field: history_field, history_value: history_value,
+        ever_blocked: ever_blocked, ever_stalled: ever_stalled,
+        currently_blocked: currently_blocked, currently_stalled: currently_stalled
+      )
+    end
+
+    def history? = !!(history_field && history_value)
+
+    def blocked_stalled? = !!(ever_blocked || ever_stalled || currently_blocked || currently_stalled)
+
+    def matches_change?(changes) = changes.any? { |c| c.field == history_field && c.value == history_value }
+  end
+
   def self.resolve_projects server_context, project_filter
     return nil if project_filter.nil?
 
@@ -76,93 +97,111 @@ class McpServer
     board.visible_columns.find { |c| c.status_ids.include?(status_id) }&.name
   end
 
-  def self.time_per_column issue, end_time
-    changes = issue.status_changes
-    _, stopped = issue.started_stopped_times
-    effective_end = stopped && stopped < end_time ? stopped : end_time
-    board = issue.board
+  # The shared iteration spine of every query tool: resolve the project filter, skip disallowed projects,
+  # and yield each surviving issue with its project name and data.
+  def self.each_allowed_issue server_context, project
+    allowed_projects = resolve_projects(server_context, project)
+    server_context[:projects].each do |project_name, project_data|
+      next if allowed_projects && !allowed_projects.include?(project_name)
 
-    result = Hash.new(0.0)
-
-    if changes.empty?
-      col = column_name_for(board, issue.status.id) || issue.status.name
-      duration = effective_end - issue.created
-      result[col] += duration if duration.positive?
-      return result
+      project_data[:issues].each do |issue|
+        yield issue, project_name, project_data
+      end
     end
+  end
 
-    first_change = changes.first
-    initial_col = column_name_for(board, first_change.old_value_id) || first_change.old_value
-    initial_duration = first_change.time - issue.created
-    result[initial_col] += initial_duration if initial_duration.positive?
-
-    changes.each_cons(2) do |prev_change, next_change|
-      col = column_name_for(board, prev_change.value_id) || prev_change.value
-      duration = next_change.time - prev_change.time
-      result[col] += duration if duration.positive?
+  # Collects the non-nil rows a block returns for each allowed issue (the row-oriented tools).
+  def self.collect_rows server_context, project
+    rows = []
+    each_allowed_issue(server_context, project) do |issue, project_name, project_data|
+      row = yield issue, project_name, project_data
+      rows << row if row
     end
+    rows
+  end
 
-    last_change = changes.last
-    final_col = column_name_for(board, last_change.value_id) || last_change.value
-    final_duration = effective_end - last_change.time
-    result[final_col] += final_duration if final_duration.positive?
+  # Renders already-sorted rows as a text Response: the empty-message when there are none, otherwise
+  # each row formatted by the block and newline-joined.
+  def self.render_rows rows, empty:, &block
+    text = rows.empty? ? empty : rows.map(&block).join("\n")
+    MCP::Tool::Response.new([{ type: 'text', text: text }])
+  end
 
-    result
+  # Shared current-state filter for the aging and not-yet-started tools.
+  def self.matches_current_state? issue, current_status, current_column
+    return false if current_status && issue.status.name != current_status
+    return false if current_column && column_name_for(issue.board, issue.status.id) != current_column
+
+    true
   end
 
-  def self.time_per_status issue, end_time
+  # Walks an issue's status timeline as spans (created -> first change, between consecutive changes,
+  # last change -> effective end) and sums each span's duration under a bucket name. The bucket for a
+  # span is chosen by the block, given the (status_name, status_id) that describe the status held during
+  # that span: for the opening span that's the first change's old value, and thereafter the change's value.
+  def self.accumulate_spans issue, end_time
     changes = issue.status_changes
     _, stopped = issue.started_stopped_times
     effective_end = stopped && stopped < end_time ? stopped : end_time
-
     result = Hash.new(0.0)
 
     if changes.empty?
-      duration = effective_end - issue.created
-      result[issue.status.name] += duration if duration.positive?
+      add_span(result, yield(issue.status.name, issue.status.id), effective_end - issue.created)
       return result
     end
 
     first_change = changes.first
-    initial_duration = first_change.time - issue.created
-    result[first_change.old_value] += initial_duration if initial_duration.positive?
+    add_span(result, yield(first_change.old_value, first_change.old_value_id), first_change.time - issue.created)
 
     changes.each_cons(2) do |prev_change, next_change|
-      duration = next_change.time - prev_change.time
-      result[prev_change.value] += duration if duration.positive?
+      add_span(result, yield(prev_change.value, prev_change.value_id), next_change.time - prev_change.time)
     end
 
     last_change = changes.last
-    final_duration = effective_end - last_change.time
-    result[last_change.value] += final_duration if final_duration.positive?
-
+    add_span(result, yield(last_change.value, last_change.value_id), effective_end - last_change.time)
     result
   end
 
+  def self.add_span result, name, duration
+    result[name] += duration if duration.positive?
+  end
+
+  def self.time_per_column issue, end_time
+    board = issue.board
+    accumulate_spans(issue, end_time) { |name, id| column_name_for(board, id) || name }
+  end
+
+  def self.time_per_status issue, end_time
+    accumulate_spans(issue, end_time) { |name, _id| name }
+  end
+
   def self.flow_efficiency_percent issue, end_time
     active_time, total_time = issue.flow_efficiency_numbers(end_time: end_time)
     total_time.positive? ? (active_time / total_time * 100).round(1) : nil
   end
 
-  def self.matches_blocked_stalled?(bsc, ever_blocked, ever_stalled, currently_blocked, currently_stalled)
-    return false if ever_blocked && bsc.none?(&:blocked?)
-    return false if ever_stalled && bsc.none?(&:stalled?)
-    return false if currently_blocked && !bsc.last&.blocked?
-    return false if currently_stalled && !bsc.last&.stalled?
+  def self.matches_blocked?(bsc, filter)
+    return false if filter.ever_blocked && bsc.none?(&:blocked?)
+    return false if filter.currently_blocked && !bsc.last&.blocked?
 
     true
   end
 
-  def self.matches_history?(issue, end_time, history_field, history_value,
-                            ever_blocked, ever_stalled, currently_blocked, currently_stalled)
-    return false if history_field && history_value &&
-                    issue.changes.none? { |c| c.field == history_field && c.value == history_value }
+  def self.matches_stalled?(bsc, filter)
+    return false if filter.ever_stalled && bsc.none?(&:stalled?)
+    return false if filter.currently_stalled && !bsc.last&.stalled?
 
-    if ever_blocked || ever_stalled || currently_blocked || currently_stalled
-      bsc = issue.blocked_stalled_changes(end_time: end_time)
-      return false unless matches_blocked_stalled?(bsc, ever_blocked, ever_stalled,
-                                                   currently_blocked, currently_stalled)
-    end
+    true
+  end
+
+  def self.matches_blocked_stalled?(bsc, filter)
+    matches_blocked?(bsc, filter) && matches_stalled?(bsc, filter)
+  end
+
+  def self.matches_history?(issue, end_time, filter)
+    return false if filter.history? && !filter.matches_change?(issue.changes)
+    return false if filter.blocked_stalled? &&
+                    !matches_blocked_stalled?(issue.blocked_stalled_changes(end_time: end_time), filter)
 
     true
   end
@@ -221,56 +260,45 @@ class McpServer
     )
 
     def self.call(server_context:, min_age_days: nil, project: nil, project_name: nil,
-                  current_status: nil, current_column: nil,
-                  history_field: nil, history_value: nil, ever_blocked: nil, ever_stalled: nil,
-                  currently_blocked: nil, currently_stalled: nil, **)
+                  current_status: nil, current_column: nil, **history_args)
       project ||= project_name
-      rows = []
-      allowed_projects = McpServer.resolve_projects(server_context, project)
-
-      server_context[:projects].each do |project_name, project_data|
-        next if allowed_projects && !allowed_projects.include?(project_name)
-
-        today = project_data[:today]
-        project_data[:issues].each do |issue|
-          started, stopped = issue.started_stopped_times
-          next unless started && !stopped
-          next if current_status && issue.status.name != current_status
-          next if current_column && McpServer.column_name_for(issue.board, issue.status.id) != current_column
-
-          age = (today - started.to_date).to_i + 1
-          next if min_age_days && age < min_age_days
-          unless McpServer.matches_history?(issue, project_data[:end_time],
-                                            history_field, history_value, ever_blocked, ever_stalled,
-                                            currently_blocked, currently_stalled)
-            next
-          end
-
-          rows << {
-            key: issue.key,
-            summary: issue.summary,
-            status: issue.status.name,
-            type: issue.type,
-            age_days: age,
-            flow_efficiency: McpServer.flow_efficiency_percent(issue, project_data[:end_time]),
-            project: project_name
-          }
-        end
-      end
+      filter = McpServer::HistoryFilter.from(**history_args)
 
+      rows = McpServer.collect_rows(server_context, project) do |issue, name, project_data|
+        build_row(
+          issue: issue, project_name: name, project_data: project_data, min_age_days: min_age_days,
+          current_status: current_status, current_column: current_column, filter: filter
+        )
+      end
       rows.sort_by! { |r| -r[:age_days] }
 
-      if rows.empty?
-        text = 'No aging work found.'
-      else
-        lines = rows.map do |r|
-          fe = r[:flow_efficiency] ? " | FE: #{r[:flow_efficiency]}%" : ''
-          "#{r[:key]} | #{r[:project]} | #{r[:type]} | #{r[:status]} | Age: #{r[:age_days]}d#{fe} | #{r[:summary]}"
-        end
-        text = lines.join("\n")
-      end
+      McpServer.render_rows(rows, empty: 'No aging work found.') { |r| format_line(r) }
+    end
 
-      MCP::Tool::Response.new([{ type: 'text', text: text }])
+    def self.build_row issue:, project_name:, project_data:, min_age_days:, current_status:, current_column:, filter:
+      started, stopped = issue.started_stopped_times
+      return nil unless started && !stopped
+      return nil unless McpServer.matches_current_state?(issue, current_status, current_column)
+
+      age = (project_data[:today] - started.to_date).to_i + 1
+      return nil if min_age_days && age < min_age_days
+      return nil unless McpServer.matches_history?(issue, project_data[:end_time], filter)
+
+      {
+        key: issue.key,
+        summary: issue.summary,
+        status: issue.status.name,
+        type: issue.type,
+        age_days: age,
+        flow_efficiency: McpServer.flow_efficiency_percent(issue, project_data[:end_time]),
+        project: project_name
+      }
+    end
+
+    def self.format_line row
+      fe = row[:flow_efficiency] ? " | FE: #{row[:flow_efficiency]}%" : ''
+      "#{row[:key]} | #{row[:project]} | #{row[:type]} | #{row[:status]} | " \
+        "Age: #{row[:age_days]}d#{fe} | #{row[:summary]}"
     end
   end
 
@@ -302,26 +330,42 @@ class McpServer
       }
     )
 
-    def self.build_row issue, project_name, started, stopped, cutoff, completed_status, completed_resolution,
-                       end_time, history_field, history_value, ever_blocked, ever_stalled,
-                       currently_blocked, currently_stalled
+    def self.call(server_context:, days_back: nil, project: nil, project_name: nil,
+                  completed_status: nil, completed_resolution: nil, **history_args)
+      project ||= project_name
+      filter = McpServer::HistoryFilter.from(**history_args)
+
+      rows = McpServer.collect_rows(server_context, project) do |issue, name, project_data|
+        build_row(
+          issue: issue, project_name: name, project_data: project_data, days_back: days_back,
+          completed_status: completed_status, completed_resolution: completed_resolution, filter: filter
+        )
+      end
+      rows.sort_by! { |r| -r[:completed_date].to_time.to_i }
+
+      McpServer.render_rows(rows, empty: 'No completed work found.') { |r| format_line(r) }
+    end
+
+    def self.build_row(
+      issue:, project_name:, project_data:, days_back:, completed_status:, completed_resolution:, filter:
+    )
+      started, stopped = issue.started_stopped_times
+      return nil unless stopped
+
       completed_date = stopped.to_date
-      return nil if cutoff && completed_date < cutoff
+      return nil if past_cutoff?(completed_date, project_data[:today], days_back)
 
       status_at_done, resolution_at_done = issue.status_resolution_at_done
-      return nil if completed_status && status_at_done&.name != completed_status
-      return nil if completed_resolution && completed_resolution != resolution_at_done
-      return nil unless McpServer.matches_history?(issue, end_time,
-                                                   history_field, history_value, ever_blocked, ever_stalled,
-                                                   currently_blocked, currently_stalled)
+      return nil unless matches_completion?(status_at_done, resolution_at_done,
+                                            completed_status, completed_resolution)
+      return nil unless McpServer.matches_history?(issue, project_data[:end_time], filter)
 
-      cycle_time = started ? (completed_date - started.to_date).to_i + 1 : nil
       {
         key: issue.key,
         summary: issue.summary,
         type: issue.type,
         completed_date: completed_date,
-        cycle_time_days: cycle_time,
+        cycle_time_days: started ? (completed_date - started.to_date).to_i + 1 : nil,
         flow_efficiency: McpServer.flow_efficiency_percent(issue, stopped),
         status_at_done: status_at_done&.name,
         resolution_at_done: resolution_at_done,
@@ -329,47 +373,25 @@ class McpServer
       }
     end
 
-    def self.call(server_context:, days_back: nil, project: nil, project_name: nil,
-                  completed_status: nil, completed_resolution: nil,
-                  history_field: nil, history_value: nil, ever_blocked: nil, ever_stalled: nil,
-                  currently_blocked: nil, currently_stalled: nil, **)
-      project ||= project_name
-      rows = []
-      allowed_projects = McpServer.resolve_projects(server_context, project)
-
-      server_context[:projects].each do |project_name, project_data|
-        next if allowed_projects && !allowed_projects.include?(project_name)
+    def self.past_cutoff? completed_date, today, days_back
+      return false unless days_back
 
-        today = project_data[:today]
-        cutoff = today - days_back if days_back
-
-        project_data[:issues].each do |issue|
-          started, stopped = issue.started_stopped_times
-          next unless stopped
-
-          row = build_row(issue, project_name, started, stopped, cutoff, completed_status, completed_resolution,
-                          project_data[:end_time], history_field, history_value, ever_blocked, ever_stalled,
-                          currently_blocked, currently_stalled)
-          rows << row if row
-        end
-      end
+      completed_date < today - days_back
+    end
 
-      rows.sort_by! { |r| -r[:completed_date].to_time.to_i }
+    def self.matches_completion? status_at_done, resolution_at_done, completed_status, completed_resolution
+      return false if completed_status && status_at_done&.name != completed_status
+      return false if completed_resolution && completed_resolution != resolution_at_done
 
-      if rows.empty?
-        text = 'No completed work found.'
-      else
-        lines = rows.map do |r|
-          ct = r[:cycle_time_days] ? "#{r[:cycle_time_days]}d" : 'unknown'
-          fe = r[:flow_efficiency] ? " | FE: #{r[:flow_efficiency]}%" : ''
-          completion = [r[:status_at_done], r[:resolution_at_done]].compact.join(' / ')
-          "#{r[:key]} | #{r[:project]} | #{r[:type]} | #{r[:completed_date]} | " \
-            "Cycle time: #{ct}#{fe} | #{completion} | #{r[:summary]}"
-        end
-        text = lines.join("\n")
-      end
+      true
+    end
 
-      MCP::Tool::Response.new([{ type: 'text', text: text }])
+    def self.format_line row
+      ct = row[:cycle_time_days] ? "#{row[:cycle_time_days]}d" : 'unknown'
+      fe = row[:flow_efficiency] ? " | FE: #{row[:flow_efficiency]}%" : ''
+      completion = [row[:status_at_done], row[:resolution_at_done]].compact.join(' / ')
+      "#{row[:key]} | #{row[:project]} | #{row[:type]} | #{row[:completed_date]} | " \
+        "Cycle time: #{ct}#{fe} | #{completion} | #{row[:summary]}"
     end
   end
 
@@ -397,49 +419,40 @@ class McpServer
     )
 
     def self.call(server_context:, project: nil, project_name: nil, current_status: nil, current_column: nil,
-                  history_field: nil, history_value: nil, ever_blocked: nil, ever_stalled: nil,
-                  currently_blocked: nil, currently_stalled: nil, **)
+                  **history_args)
       project ||= project_name
-      rows = []
-      allowed_projects = McpServer.resolve_projects(server_context, project)
-
-      server_context[:projects].each do |project_name, project_data|
-        next if allowed_projects && !allowed_projects.include?(project_name)
-
-        project_data[:issues].each do |issue|
-          started, stopped = issue.started_stopped_times
-          next if started || stopped
-          next if current_status && issue.status.name != current_status
-          next if current_column && McpServer.column_name_for(issue.board, issue.status.id) != current_column
-          unless McpServer.matches_history?(issue, project_data[:end_time],
-                                            history_field, history_value, ever_blocked, ever_stalled,
-                                            currently_blocked, currently_stalled)
-            next
-          end
-
-          rows << {
-            key: issue.key,
-            summary: issue.summary,
-            status: issue.status.name,
-            type: issue.type,
-            created: issue.created.to_date,
-            project: project_name
-          }
-        end
-      end
+      filter = McpServer::HistoryFilter.from(**history_args)
 
+      rows = McpServer.collect_rows(server_context, project) do |issue, name, project_data|
+        build_row(
+          issue: issue, project_name: name, project_data: project_data,
+          current_status: current_status, current_column: current_column, filter: filter
+        )
+      end
       rows.sort_by! { |r| r[:created] }
 
-      if rows.empty?
-        text = 'No unstarted work found.'
-      else
-        lines = rows.map do |r|
-          "#{r[:key]} | #{r[:project]} | #{r[:type]} | #{r[:status]} | Created: #{r[:created]} | #{r[:summary]}"
-        end
-        text = lines.join("\n")
-      end
+      McpServer.render_rows(rows, empty: 'No unstarted work found.') { |r| format_line(r) }
+    end
 
-      MCP::Tool::Response.new([{ type: 'text', text: text }])
+    def self.build_row issue:, project_name:, project_data:, current_status:, current_column:, filter:
+      started, stopped = issue.started_stopped_times
+      return nil if started || stopped
+      return nil unless McpServer.matches_current_state?(issue, current_status, current_column)
+      return nil unless McpServer.matches_history?(issue, project_data[:end_time], filter)
+
+      {
+        key: issue.key,
+        summary: issue.summary,
+        status: issue.status.name,
+        type: issue.type,
+        created: issue.created.to_date,
+        project: project_name
+      }
+    end
+
+    def self.format_line row
+      "#{row[:key]} | #{row[:project]} | #{row[:type]} | #{row[:status]} | " \
+        "Created: #{row[:created]} | #{row[:summary]}"
     end
   end
 
@@ -486,42 +499,45 @@ class McpServer
       project ||= project_name
       group_by = 'column' if column
 
-      totals = Hash.new { |h, k| h[k] = { total_seconds: 0.0, visit_count: 0 } }
-      allowed_projects = McpServer.resolve_projects(server_context, project)
+      totals = accumulate_times(server_context, project, issue_state, group_by)
+      rows = totals.map { |name, data| summary_row(name, data) }.sort_by { |r| -r[:avg_days] }
 
-      server_context[:projects].each do |project_name, project_data|
-        next if allowed_projects && !allowed_projects.include?(project_name)
-
-        project_data[:issues].each do |issue|
-          next unless select_issues(issue, issue_state)
+      McpServer.render_rows(rows, empty: 'No data found.') { |r| format_line(r, group_by) }
+    end
 
-          time_map = if group_by == 'column'
-                       McpServer.time_per_column(issue, project_data[:end_time])
-                     else
-                       McpServer.time_per_status(issue, project_data[:end_time])
-                     end
+    def self.accumulate_times server_context, project, issue_state, group_by
+      totals = Hash.new { |hash, key| hash[key] = { total_seconds: 0.0, visit_count: 0 } }
+      McpServer.each_allowed_issue(server_context, project) do |issue, _name, project_data|
+        next unless select_issues(issue, issue_state)
 
-          time_map.each do |name, seconds|
-            totals[name][:total_seconds] += seconds
-            totals[name][:visit_count] += 1
-          end
+        time_map_for(issue, project_data[:end_time], group_by).each do |name, seconds|
+          totals[name][:total_seconds] += seconds
+          totals[name][:visit_count] += 1
         end
       end
+      totals
+    end
 
-      return MCP::Tool::Response.new([{ type: 'text', text: 'No data found.' }]) if totals.empty?
-
-      rows = totals.map do |name, data|
-        total_days = (data[:total_seconds] / 86_400.0).round(1)
-        avg_days = (data[:total_seconds] / data[:visit_count] / 86_400.0).round(1)
-        { name: name, total_days: total_days, avg_days: avg_days, visit_count: data[:visit_count] }
+    def self.time_map_for issue, end_time, group_by
+      if group_by == 'column'
+        McpServer.time_per_column(issue, end_time)
+      else
+        McpServer.time_per_status(issue, end_time)
       end
-      rows.sort_by! { |r| -r[:avg_days] }
+    end
 
+    def self.summary_row name, data
+      {
+        name: name,
+        total_days: (data[:total_seconds] / 86_400.0).round(1),
+        avg_days: (data[:total_seconds] / data[:visit_count] / 86_400.0).round(1),
+        visit_count: data[:visit_count]
+      }
+    end
+
+    def self.format_line row, group_by
       label = group_by == 'column' ? 'Column' : 'Status'
-      lines = rows.map do |r|
-        "#{label}: #{r[:name]} | Avg: #{r[:avg_days]}d | Total: #{r[:total_days]}d | Issues: #{r[:visit_count]}"
-      end
-      MCP::Tool::Response.new([{ type: 'text', text: lines.join("\n") }])
+      "#{label}: #{row[:name]} | Avg: #{row[:avg_days]}d | Total: #{row[:total_days]}d | Issues: #{row[:visit_count]}"
     end
   end