snitcher_reports 0.2.0

data/lib/snitcher/sources/jira.rb

@@ -0,0 +1,523 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'time'
+require_relative '../jql_validator'
+
+module Snitcher
+  module Sources
+    # JIRA Source Fetcher — Jira Cloud REST API v3
+    #
+    # SECURITY NOTES:
+    # - The JIRA REST API does not support parameterized JQL queries
+    # - All JQL is constructed as strings with validated/escaped user input
+    # - Email addresses are validated by Validators.validate_email! (RFC 5322 regex)
+    # - Additional JQL-specific validation in JQLValidator prevents dangerous patterns
+    # - Dates are constructed by our code (not user input) but validated for format
+    # - Issue keys are validated before interpolation into URL paths
+    #
+    # ARCHITECTURE NOTES:
+    # - Jira Cloud only: /rest/api/3 with Basic auth. Data Center (/rest/api/2 + Bearer
+    #   PAT) is not supported.
+    # - Supports multi-language status names via statusCategory (not hardcoded status names)
+    # - Changelog time calculation uses statusCategory 'indeterminate' (In Progress equivalent)
+    #   which is language-independent, unlike status names ("In Arbeit", "En cours", etc.).
+    #   The changelog itself carries only status IDs and localised names, so IDs are resolved
+    #   through StatusCategories.
+    # - N+1 fetching: Jira has no public batch worklog endpoint (/rest/internal/api/
+    #   latest/worklog/bulk is internal and ASAP-authenticated), so worklogs stay at one
+    #   call per ticket. Changelogs for tickets without worklogs are batched through
+    #   POST /rest/api/3/issue/bulkfetch, 100 issues per call.
+    # - /rest/api/3/changelog/bulkfetch is not used: it filters by field and paginates the
+    #   changelogs itself, but it returns 404 on instances where /issue/bulkfetch with the
+    #   same body works, so the batching goes through the issue endpoint and pages long
+    #   changelogs itself:
+    #   https://community.developer.atlassian.com/t/bulk-fetch-changelogs-api-returns-404/87255
+    #   https://community.developer.atlassian.com/t/bulk-fetch-changelogs-experimental-api/87240
+    #
+    # rubocop:disable-next Metrics/ClassLength -- Length due to required YARD docs and helper methods
+    class Jira < Source
+      RESOLVED_CATEGORIES = %w[Done].freeze
+      # JIRA statusCategory IDs are language-independent (unlike status names)
+      # 'indeterminate' = "In Progress" category across all JIRA languages
+      IN_PROGRESS_CATEGORY_ID = 'indeterminate'
+
+      # Valid JIRA project key pattern — prevents JQL injection
+      PROJECT_KEY_PATTERN = /\A[A-Z][A-Z0-9_]+\z/
+
+      # Fields requested from /search/jql. `key` is always returned at the top level
+      # and is not a field id.
+      SEARCH_FIELDS = %w[summary status assignee resolutiondate].freeze
+
+      # Status discovery deliberately samples one page rather than paginating —
+      # see #fetch_statuses_from_issues.
+      DISCOVERY_MAX_PAGES = 1
+
+      def initialize(config = {})
+        super
+        @jira_url = (Source.presence(config[:jira_url]) || Source.env('JIRA_URL'))&.chomp('/')
+
+        # Configured status name -> category mappings (from .snitcher.yml)
+        @in_progress_names = (config[:in_progress_statuses] || []).map(&:downcase)
+        @done_names = (config[:done_statuses] || []).map(&:downcase)
+        @todo_names = (config[:todo_statuses] || []).map(&:downcase)
+
+        # JIRA project keys to filter by (from .snitcher.yml)
+        @project_keys = validate_project_keys(config[:projects] || [])
+
+        # Seam for the test suite, which stubs retryable statuses and would otherwise
+        # sleep through three real backoffs per test. Not part of .snitcher.yml.
+        @retry_interval = config.fetch(:retry_interval, Client::RETRY_INTERVAL)
+      end
+
+      def source_name
+        :jira
+      end
+
+      # Note the cast: without it the && chain returns the API token itself, which
+      # then leaks into anything that logs or inspects the result of this predicate.
+      def available?
+        !!(@jira_url && jira_username && jira_api_token)
+      end
+
+      def unavailable_reason
+        missing = []
+        missing << 'JIRA_URL' if @jira_url.nil?
+        missing << 'JIRA_USERNAME' if jira_username.nil?
+        missing << 'JIRA_API_TOKEN' if jira_api_token.nil?
+        "#{missing.join(', ')} #{missing.one? ? 'is' : 'are'} not set"
+      end
+
+      # Discover all statuses in use across JIRA projects.
+      # Samples issues through #fetch_statuses_from_issues and extracts
+      # status name -> statusCategory mappings.
+      #
+      # @param config [Hash] optional config overrides
+      # @return [Hash] status discovery result
+      def self.discover_statuses(config = {})
+        instance = new(config)
+        return { error: 'JIRA not configured' } unless instance.available?
+
+        instance.send(:fetch_jira_statuses)
+      end
+
+      # Discover all available JIRA projects for the configured instance.
+      #
+      # @param config [Hash] optional config overrides
+      # @return [Array<Hash>, Hash] array of {key:, name:} or {error:} hash
+      def self.discover_projects(config = {})
+        instance = new(config)
+        return { error: 'JIRA not configured' } unless instance.available?
+
+        instance.send(:fetch_jira_projects)
+      end
+
+      def fetch(user_email:, since:, until_time:)
+        return [] unless available?
+
+        validated_email = Validators.validate_email!(primary_email(user_email))
+        tickets = find_resolved_tickets(validated_email, since: since, until_time: until_time)
+        results = []
+        no_worklog_keys = []
+
+        tickets.each do |ticket|
+          key = ticket['key']
+          jira_display_name = ticket.dig('fields', 'assignee', 'displayName')
+          worklogs = fetch_worklogs(key)
+          user_seconds = sum_user_worklogs(worklogs, validated_email,
+                                           jira_display_name: jira_display_name)
+
+          if user_seconds.positive?
+            results << build_jira_work_item(ticket, user_seconds, :worklog)
+          else
+            no_worklog_keys << key
+          end
+        end
+
+        apply_changelog_fallback(results, no_worklog_keys, tickets)
+        results
+      end
+
+      private
+
+      # Validates and uppercases project keys to prevent JQL injection.
+      # @param keys [Array<String>] raw project key strings
+      # @return [Array<String>] validated, uppercased project keys
+      def validate_project_keys(keys)
+        keys.map do |key|
+          upcased = key.to_s.upcase
+          unless upcased.match?(PROJECT_KEY_PATTERN)
+            warn "[jira] Warning: invalid project key '#{key}' ignored (must match #{PROJECT_KEY_PATTERN.source})"
+            next nil
+          end
+          upcased
+        end.compact
+      end
+
+      # Builds JQL project filter clause from configured project keys.
+      # @return [String] "project IN (...) AND " or empty string
+      def project_clause
+        return '' if @project_keys.empty?
+
+        keys = @project_keys.map { |k| %("#{k}") }.join(', ')
+        "project IN (#{keys}) AND "
+      end
+
+      def client
+        @client ||= Client.new(base_url: @jira_url, username: jira_username,
+                               api_token: jira_api_token, retry_interval: @retry_interval)
+      end
+
+      def status_categories
+        @status_categories ||= StatusCategories.new(client)
+      end
+
+      def jira_username
+        Source.env('JIRA_USERNAME')
+      end
+
+      def jira_api_token
+        Source.env('JIRA_API_TOKEN')
+      end
+
+      # Finds resolved tickets for a user within a date range.
+      #
+      # SEMANTIC NOTE: This query uses statusCategory="Done" without requiring that tickets
+      # passed through "In Progress". This is intentional - tickets resolved directly from
+      # backlog (e.g., duplicates, won't-fix) are included, and time is calculated from
+      # worklogs or changelog fallback. The old `status WAS "In Progress"` filter was removed
+      # to support multi-language JIRA instances where status names vary.
+      #
+      # @param user_email [String] validated user email
+      # @param since [Time] start of date range
+      # @param until_time [Time] end of date range
+      # @return [Array<Hash>] array of ticket hashes
+      def find_resolved_tickets(user_email, since:, until_time:)
+        JQLValidator.validate_email_for_jql!(user_email)
+        since_str = JQLValidator.validate_date_format!(since.strftime('%Y-%m-%d'))
+        until_str = JQLValidator.validate_date_format!(until_time.strftime('%Y-%m-%d'))
+
+        status_category = RESOLVED_CATEGORIES.first
+        jql = <<~JQL.strip
+          #{project_clause}assignee = "#{user_email}" AND statusCategory = "#{status_category}"
+          AND resolved >= "#{since_str}" AND resolved <= "#{until_str}"
+          ORDER BY resolved DESC
+        JQL
+
+        client.search(jql: jql, fields: SEARCH_FIELDS)
+      end
+
+      # Validators::ValidationError is caught alongside Faraday::Error on purpose. The
+      # key comes from Jira, not from the user, and Orchestrator#fetch re-raises
+      # ValidationError to fail fast on bad input — which would discard the Git, Linear,
+      # ClickUp and Calendar results too. Remote data that fails its guard belongs with
+      # the network errors next to it: warn, and skip the one ticket.
+      def fetch_worklogs(issue_key)
+        client.worklogs(issue_key)
+      rescue Faraday::Error, Validators::ValidationError => e
+        warn "[jira] Warning: worklog fetch failed for #{issue_key} (#{e.message})"
+        []
+      end
+
+      # Sums worklog time for a specific user.
+      #
+      # @param worklogs [Array<Hash>] array of worklog entries
+      # @param user_email [String] the user's email to match
+      # @return [Integer] total seconds logged by the user
+      def sum_user_worklogs(worklogs, user_email, jira_display_name: nil)
+        # Precompute matching data once (not per-worklog) for performance
+        match_data = build_author_match_data(user_email, jira_display_name: jira_display_name)
+        worklogs
+          .select { |w| worklog_author_matches?(author_identity(w['author']), match_data) }
+          .sum { |w| w['timeSpentSeconds'].to_i }
+      end
+
+      # Reduces a Jira worklog author to the single string #worklog_author_matches?
+      # works on. emailAddress is absent when the account's privacy settings hide it
+      # (GDPR), in which case the display-name heuristic takes over.
+      #
+      # This is the seam where exact accountId matching would attach later; the
+      # heuristic would stay as the fallback for hidden emails.
+      #
+      # @param author [Hash, String, nil] REST returns a Hash; a String is tolerated
+      # @return [String, nil]
+      def author_identity(author)
+        return author unless author.is_a?(Hash)
+
+        author['emailAddress'] || author['displayName']
+      end
+
+      # Builds precomputed data for author matching.
+      # Called once per user, not per worklog.
+      #
+      # @param user_email [String] the user's email
+      # @param jira_display_name [String, nil] the user's Jira display name from the assignee field
+      # @return [Hash] match data with :email, :username, :name_parts, :display_name keys
+      def build_author_match_data(user_email, jira_display_name: nil)
+        email_lower = user_email.downcase
+        # Extract username, stripping any +tag suffix (e.g., john.smith+tag@example.com -> john.smith)
+        username = email_lower.split('@').first.gsub(/\+.*/, '')
+        # Split on dots to get name parts, capitalize for display name matching
+        # e.g., "john.smith" -> ["John", "Smith"]
+        # Filter out parts shorter than 2 chars to avoid overly broad matches (e.g., "S" matching too many)
+        name_parts = username.split('.').map(&:capitalize).select { |p| p.length >= 2 }
+
+        { email: email_lower, username: username, name_parts: name_parts,
+          display_name: jira_display_name&.downcase }
+      end
+
+      # Checks if a worklog author matches the target user.
+      #
+      # Matching strategy (in order of precedence):
+      # 0. Exact Jira display name match (from ticket assignee field)
+      # 1. Exact email match (case-insensitive)
+      # 2. Exact username match (case-insensitive)
+      # 3. Display name contains all name parts (case-insensitive)
+      #    e.g., "John Smith" matches user "john.smith@example.com"
+      #
+      # @param author [String, nil] the worklog author identifier (email, username, or display name)
+      # @param match_data [Hash] precomputed match data from build_author_match_data
+      # @return [Boolean] true if author matches the target user
+      # @note Display name matching is heuristic and may have false positives for common names
+      def worklog_author_matches?(author, match_data)
+        return false unless author
+
+        author_lower = author.downcase
+
+        # Strategy 0: Exact Jira display name match (e.g. "Arek" from ticket assignee)
+        return true if match_data[:display_name] && author_lower == match_data[:display_name]
+
+        # Strategy 1: Exact email match
+        return true if author_lower == match_data[:email]
+
+        # Strategy 2: Exact username match
+        return true if author_lower == match_data[:username]
+
+        # Strategy 3: Display name contains all name parts (case-insensitive)
+        # Each name part must appear somewhere in the author string
+        match_data[:name_parts].all? { |part| author_lower.include?(part.downcase) }
+      end
+
+      # Fills in time for tickets that carried no worklogs, from their status history.
+      #
+      # The changelogs are fetched in bulk before the loop and joined by key, the shape
+      # ClickUp#apply_status_time_fallback uses — one call per 100 tickets instead of one
+      # per ticket. A ticket missing from the response yields no time rather than being
+      # dropped, so a partial bulk response still produces a complete ticket list.
+      def apply_changelog_fallback(results, no_worklog_keys, tickets)
+        return if no_worklog_keys.empty?
+
+        tickets_by_key = tickets.to_h { |t| [t['key'], t] }
+        changelogs_by_key = fetch_changelogs(no_worklog_keys)
+
+        no_worklog_keys.each do |key|
+          ticket = tickets_by_key[key]
+          next unless ticket
+
+          seconds = calculate_time_from_changelog(changelogs_by_key[key])
+          results << build_jira_work_item(ticket, seconds, :calculated)
+        end
+      end
+
+      # No rescue here on purpose. Client#changelogs already warns past the failures a
+      # report can absorb — a rejected key, a failed slice, a single unreadable ticket —
+      # and returns what it did read. What reaches this method is a run in which no
+      # changelog at all could be fetched, and swallowing that would report every ticket
+      # in the run as zero hours while the report still called itself complete. Raising
+      # puts the source in Orchestrator#failed_sources instead.
+      #
+      # @param issue_keys [Array<String>] keys of the tickets that had no worklogs
+      # @return [Hash{String => Array<Hash>}] issue key => changelog histories
+      def fetch_changelogs(issue_keys)
+        client.changelogs(issue_keys)
+      end
+
+      # Calculates time spent in "In Progress" status from changelog entries.
+      #
+      # Uses statusCategory key ('indeterminate') instead of status name to support
+      # multi-language JIRA instances where status names vary (e.g., "In Arbeit",
+      # "En cours", "In Progress").
+      #
+      # @param changelogs [Array<Hash>, nil] changelog history entries
+      # @return [Integer] total seconds spent in "In Progress" statusCategory
+      def calculate_time_from_changelog(changelogs)
+        return 0 if changelogs.nil? || changelogs.empty?
+
+        entries = changelogs.sort_by { |c| Time.parse(c['created']) }
+        total_seconds = 0
+        in_progress_start = nil
+
+        entries.each do |entry|
+          timestamp = Time.parse(entry['created'])
+          status_change = (entry['items'] || []).find { |i| i['field'] == 'status' }
+          next unless status_change
+
+          # Use statusCategory key (language-independent) if available,
+          # fall back to status name for backward compatibility
+          to_category = extract_status_category(status_change)
+
+          if to_category == IN_PROGRESS_CATEGORY_ID
+            in_progress_start = timestamp
+          elsif in_progress_start
+            total_seconds += WorkingHoursCalculator.seconds_between(in_progress_start, timestamp, @working_hours)
+            in_progress_start = nil
+          end
+        end
+        total_seconds
+      end
+
+      # Extracts the language-independent statusCategory key for a status change.
+      #
+      # The changelog gives only IDs and localised names: `to` is the numeric status ID,
+      # `toString` its display name.
+      #
+      # Precedence, highest first:
+      #   1. names configured in .snitcher.yml — an explicit decision by the operator,
+      #      and the only path that existed before the catalogue was introduced, so an
+      #      org that classified "In Review" as in-progress keeps its reported hours;
+      #   2. the instance's status catalogue — authoritative and language-independent;
+      #   3. hardcoded English names — a guess, for statuses the catalogue does not know
+      #      and for the case where it could not be fetched at all.
+      #
+      # @param status_change [Hash] the changelog item for a status change
+      # @return [String, nil] 'new', 'indeterminate', 'done', or nil
+      def extract_status_category(status_change)
+        name = status_change['toString']
+
+        map_configured_status_name(name) ||
+          status_categories.category_for(status_change['to']) ||
+          map_english_status_name(name)
+      end
+
+      # Maps a status name to a category key using the names configured in
+      # .snitcher.yml (sources.jira.in_progress_statuses and friends).
+      #
+      # @param status_name [String, nil] the status name
+      # @return [String, nil] the category key or nil
+      def map_configured_status_name(status_name)
+        return nil unless status_name
+
+        name = status_name.downcase
+
+        return IN_PROGRESS_CATEGORY_ID if @in_progress_names.include?(name)
+        return 'done' if @done_names.include?(name)
+        return 'new' if @todo_names.include?(name)
+
+        nil
+      end
+
+      # Maps hardcoded English status names to category keys — the last resort, for
+      # statuses the catalogue does not carry and for a catalogue that could not be
+      # fetched. Only correct for English instances, which is why it ranks below both
+      # the configured names and the catalogue.
+      #
+      # @param status_name [String, nil] the status name
+      # @return [String, nil] the category key or nil
+      def map_english_status_name(status_name)
+        return nil unless status_name
+
+        case status_name.downcase
+        when 'in progress', 'in development', 'in review'
+          IN_PROGRESS_CATEGORY_ID
+        when 'done', 'closed', 'resolved'
+          'done'
+        when 'to do', 'open', 'backlog'
+          'new'
+        end
+      end
+
+      # Fetches and categorizes JIRA statuses.
+      # @return [Hash] categorized statuses or error
+      def fetch_jira_statuses
+        categorize_statuses(fetch_statuses_from_issues)
+      rescue StandardError => e
+        { error: "Failed to fetch JIRA statuses: #{e.message}" }
+      end
+
+      # Fetches all available JIRA projects.
+      # @return [Array<Hash>, Hash] array of {key:, name:} or {error:} hash
+      def fetch_jira_projects
+        client.projects.map { |p| { key: p['key'], name: p['name'] } }
+      rescue StandardError => e
+        { error: "Failed to fetch JIRA projects: #{e.message}" }
+      end
+
+      # Samples statuses from the last 100 updated issues.
+      #
+      # NOTE: This is a sampling approach, not exhaustive discovery — it is capped at one
+      # page (DISCOVERY_MAX_PAGES) on purpose. Enumerating /rest/api/3/status would return
+      # every status on the instance but would lose the sources.jira.projects scoping that
+      # this JQL applies, so sampling stays.
+      #
+      # @return [Array<Hash>] unique statuses with name and category_key
+      def fetch_statuses_from_issues
+        issues = client.search(jql: "#{project_clause}updated >= -365d ORDER BY updated DESC",
+                               fields: %w[status], max_pages: DISCOVERY_MAX_PAGES)
+
+        status_map = {}
+        issues.each do |issue|
+          status = issue.dig('fields', 'status')
+          next unless status
+
+          name = status['name']
+          next unless name
+
+          # statusCategory.key is language-independent. A v3 status object always carries
+          # it (its colour lives at statusCategory.colorName, not on the status), so a
+          # missing key leaves the status uncategorised rather than guessing.
+          status_map[name] ||= { name: name, category_key: status.dig('statusCategory', 'key') }
+        end
+        status_map.values
+      end
+
+      # Categorizes statuses by their JIRA statusCategory key.
+      #
+      # JIRA statusCategory keys are language-independent:
+      # - 'done'          -> done_statuses (completed work)
+      # - 'indeterminate' -> in_progress_statuses (active work)
+      # - 'new'           -> todo_statuses (not started)
+      #
+      # @param statuses [Array<Hash>] statuses with :name and :category_key
+      # @return [Hash] categorized statuses
+      def categorize_statuses(statuses)
+        # Single-pass categorization for performance
+        categorized = { done: [], in_progress: [], todo: [] }
+        statuses.each do |s|
+          case s[:category_key]
+          when 'done'          then categorized[:done] << s[:name]
+          when 'indeterminate' then categorized[:in_progress] << s[:name]
+          when 'new'           then categorized[:todo] << s[:name]
+          end
+        end
+
+        {
+          done_statuses: categorized[:done],
+          in_progress_statuses: categorized[:in_progress],
+          todo_statuses: categorized[:todo],
+          all_statuses: statuses
+        }
+      end
+
+      # Builds a WorkItem from a JIRA ticket.
+      #
+      # @param ticket [Hash] the JIRA issue: 'key' at the top level, everything else under 'fields'
+      # @param time_seconds [Integer] time spent in seconds
+      # @param time_source [Symbol] source of time data (:worklog or :calculated)
+      # @return [WorkItem] the constructed work item
+      def build_jira_work_item(ticket, time_seconds, time_source)
+        fields = ticket['fields'] || {}
+        resolution_date = fields['resolutiondate']
+
+        build_work_item(
+          external_id: ticket['key'],
+          title: fields['summary'],
+          completed_at: resolution_date ? Time.parse(resolution_date) : nil,
+          time_spent_seconds: time_seconds.positive? ? time_seconds : nil,
+          time_source: time_seconds.positive? ? time_source : nil,
+          url: "#{@jira_url}/browse/#{ticket['key']}",
+          metadata: { status: fields.dig('status', 'name') }
+        )
+      end
+    end
+  end
+end