snitcher_reports 0.2.0

data/lib/snitcher/sources/linear.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/retry'
+require 'json'
+require 'time'
+
+module Snitcher
+  module Sources
+    class Linear < Source
+      API_URL = 'https://api.linear.app/graphql'
+      PAGE_SIZE = 100
+      MAX_PAGES = 10 # Safety limit to prevent infinite loops
+
+      def initialize(config = {})
+        super
+        @api_key = Source.presence(config[:api_key]) || Source.env('LINEAR_API_KEY')
+      end
+
+      def source_name
+        :linear
+      end
+
+      def available?
+        !@api_key.nil?
+      end
+
+      def unavailable_reason
+        'LINEAR_API_KEY is not set'
+      end
+
+      # Discover all workflow states across Linear teams.
+      # Uses the `type` field (language-independent) to categorize states.
+      #
+      # @param config [Hash] optional config overrides
+      # @return [Hash] status discovery result
+      def self.discover_statuses(config = {})
+        instance = new(config)
+        return { error: 'Linear not configured' } unless instance.available?
+
+        instance.send(:fetch_workflow_states)
+      end
+
+      def fetch(user_email:, since:, until_time:)
+        return [] unless available?
+
+        user_id = find_user_id(primary_email(user_email))
+        return [] unless user_id
+
+        issues = fetch_completed_issues(user_id: user_id, since: since, until_time: until_time)
+
+        issues.map do |issue|
+          cycle_time = calculate_cycle_time(issue)
+
+          build_work_item(
+            external_id: issue['identifier'],
+            title: issue['title'],
+            completed_at: safe_parse_iso8601(issue['completedAt']),
+            time_spent_seconds: cycle_time,
+            time_source: cycle_time ? :calculated : nil,
+            url: issue['url'],
+            metadata: {
+              estimate: issue['estimate'],
+              state: issue.dig('state', 'name'),
+              cycle: issue.dig('cycle', 'name'),
+              project: issue.dig('project', 'name'),
+              started_at: issue['startedAt']
+            }
+          )
+        end
+      end
+
+      private
+
+      def connection
+        @connection ||= Faraday.new(url: API_URL) do |f|
+          f.request :json
+          f.request :retry, max: 3, interval: 0.5, retry_statuses: [429, 500, 502, 503, 504]
+          f.response :json
+          f.headers['Authorization'] = @api_key
+          f.headers['Content-Type'] = 'application/json'
+          f.options.timeout = 15
+          f.options.open_timeout = 5
+        end
+      end
+
+      def query(graphql_query, variables = {})
+        response = connection.post do |req|
+          req.body = { query: graphql_query, variables: variables }.to_json
+        end
+
+        data = response.body
+        raise Error, data['errors'].map { |e| e['message'] }.join(', ') if data['errors']
+
+        data['data']
+      end
+
+      def find_user_id(email)
+        result = query(<<~GRAPHQL, email: email)
+          query($email: String!) {
+            users(filter: { email: { eq: $email } }) {
+              nodes {
+                id
+              }
+            }
+          }
+        GRAPHQL
+
+        result.dig('users', 'nodes', 0, 'id')
+      end
+
+      def fetch_completed_issues(user_id:, since:, until_time:)
+        all_issues = []
+        cursor = nil
+        page = 0
+
+        loop do
+          result = query(issues_query, userId: user_id, since: since.iso8601, until: until_time.iso8601, cursor: cursor)
+
+          issues_data = result['issues'] || {}
+          nodes = issues_data['nodes'] || []
+          all_issues.concat(nodes)
+
+          page_info = issues_data['pageInfo'] || {}
+          break unless page_info['hasNextPage']
+
+          cursor = page_info['endCursor']
+          page += 1
+          break if page >= MAX_PAGES
+        end
+
+        all_issues
+      end
+
+      def issues_query
+        <<~GRAPHQL
+          query($userId: ID!, $since: DateTimeOrDuration!, $until: DateTimeOrDuration!, $cursor: String) {
+            issues(
+              filter: {
+                assignee: { id: { eq: $userId } }
+                completedAt: { gte: $since, lte: $until }
+              }
+              first: #{PAGE_SIZE}
+              after: $cursor
+            ) {
+              pageInfo {
+                hasNextPage
+                endCursor
+              }
+              nodes {
+                id
+                identifier
+                title
+                url
+                completedAt
+                startedAt
+                createdAt
+                estimate
+                state { name }
+                cycle { name }
+                project { name }
+              }
+            }
+          }
+        GRAPHQL
+      end
+
+      # Calculate cycle time (completedAt - startedAt), filtered by working hours when configured.
+      # When working_hours config is nil, returns raw wall-clock seconds (backward compatible).
+      #
+      # NOTE: Unlike Jira's worklog-based time, this is derived from two timestamps
+      # (completedAt - startedAt), so working-hours filtering is an approximation.
+      #
+      # @param issue [Hash] Linear issue with 'startedAt' and 'completedAt' fields
+      # @return [Integer, nil] seconds (0 or positive when working_hours configured,
+      #   may be negative for inverted timestamps when working_hours is nil), or nil if timestamps missing
+      def calculate_cycle_time(issue)
+        return nil unless issue['startedAt'] && issue['completedAt']
+
+        # Time.iso8601 is stricter than Time.parse — Linear API guarantees ISO 8601 format;
+        # stricter parsing prevents silent misparse of unexpected formats.
+        started = Time.iso8601(issue['startedAt'])
+        completed = Time.iso8601(issue['completedAt'])
+        WorkingHoursCalculator.seconds_between(started, completed, @working_hours)
+      rescue ArgumentError => e
+        warn "[Snitcher::Linear] failed to parse timestamps for #{issue['identifier']}: #{e.message}"
+        nil
+      end
+
+      # Safely parse an ISO 8601 timestamp string.
+      # Returns nil for nil/empty input or malformed strings (logs a warning).
+      def safe_parse_iso8601(value)
+        return nil if value.nil? || value.empty?
+
+        Time.iso8601(value)
+      rescue ArgumentError => e
+        warn "[Snitcher::Linear] failed to parse timestamp '#{value}': #{e.message}"
+        nil
+      end
+
+      # Fetches all workflow states from Linear and categorizes them by type.
+      #
+      # Linear workflow state types are language-independent:
+      # - 'completed' -> done_statuses
+      # - 'started'   -> in_progress_statuses
+      # - 'unstarted' -> todo_statuses
+      # - 'canceled'  -> canceled_statuses
+      #
+      # NOTE: This query fetches up to 200 workflow states (GraphQL pagination limit).
+      # Workspaces with more than 200 states across all teams will have some states
+      # truncated. This is rare in practice.
+      #
+      # @return [Hash] categorized statuses or error
+      def fetch_workflow_states
+        result = query(<<~GRAPHQL)
+          query {
+            workflowStates(first: 200) {
+              nodes {
+                id
+                name
+                type
+                color
+                team { id key name }
+              }
+            }
+          }
+        GRAPHQL
+
+        states = result.dig('workflowStates', 'nodes') || []
+
+        # Single-pass categorization for performance (O(n) instead of O(5n))
+        categorized = { done: Set.new, in_progress: Set.new, todo: Set.new, canceled: Set.new, all: [] }
+        states.each do |s|
+          state_name = s['name']
+          categorized[:all] << { name: state_name, type: s['type'], team: s.dig('team', 'key') }
+
+          case s['type']
+          when 'completed' then categorized[:done] << state_name
+          when 'started'   then categorized[:in_progress] << state_name
+          when 'unstarted' then categorized[:todo] << state_name
+          when 'canceled'  then categorized[:canceled] << state_name
+          end
+        end
+
+        {
+          done_statuses: categorized[:done].to_a,
+          in_progress_statuses: categorized[:in_progress].to_a,
+          todo_statuses: categorized[:todo].to_a,
+          canceled_statuses: categorized[:canceled].to_a,
+          all_statuses: categorized[:all].uniq
+        }
+      rescue StandardError => e
+        { error: "Failed to fetch Linear workflow states: #{e.message}" }
+      end
+    end
+  end
+end

data/lib/snitcher/sources/source.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Snitcher
+  module Sources
+    # Base class for all data sources.
+    #
+    # == Creating a New Source
+    #
+    # To add a new data source:
+    #
+    # 1. Create a new class inheriting from Source in lib/snitcher/sources/
+    # 2. Implement the required methods: #source_name, #available?, #fetch
+    # 3. Optionally override #unavailable_reason to say what setting is missing
+    # 4. Register the source in Orchestrator::SOURCE_MAP (lib/snitcher/orchestrator.rb)
+    #
+    # == Example
+    #
+    #   class MySource < Source
+    #     def source_name
+    #       :my_source
+    #     end
+    #
+    #     def available?
+    #       !Source.env('MY_SOURCE_API_KEY').nil?
+    #     end
+    #
+    #     def fetch(user_email:, since:, until_time:)
+    #       # Fetch and return array of WorkItems
+    #       []
+    #     end
+    #   end
+    #
+    #   # Then in orchestrator.rb, add to SOURCE_MAP:
+    #   SOURCE_MAP = {
+    #     # ... existing sources ...
+    #     my_source: Sources::MySource
+    #   }.freeze
+    #
+    class Source
+      # Working hours this source filters calculated time to, or nil for raw wall-clock.
+      # Seeded from the config the source was built with; Orchestrator replaces it per
+      # person when working_hours.people names whoever a report is for. One writable slot
+      # is enough because the orchestrator builds its sources once and walks people
+      # sequentially (see Client#work_reports) — there is never a second person in flight.
+      attr_accessor :working_hours
+
+      def initialize(config = {})
+        @config = config
+        @working_hours = config[:working_hours]
+      end
+
+      # @return [Symbol] unique identifier for this source (e.g., :jira, :git)
+      def source_name
+        raise NotImplementedError, "#{self.class} must implement #source_name"
+      end
+
+      # @return [Boolean] true if the source is configured and ready to use
+      def available?
+        raise NotImplementedError, "#{self.class} must implement #available?"
+      end
+
+      # Why #available? is false, as one operator-facing phrase naming the setting to change.
+      # Read only when #available? is false: Orchestrator puts it verbatim into failed_sources
+      # and on stderr, so a skipped source says what it needs rather than only that something
+      # is missing. Override to be specific — the default is honest but blunt.
+      # @return [String]
+      def unavailable_reason
+        'not configured'
+      end
+
+      # Fetch work items from the source.
+      #
+      # The Orchestrator resolves each user to one or more source-specific emails
+      # (see sources.<name>.emails / .user), so +user_email+ may be a single String
+      # or an Array<String>. Use #user_emails / #primary_email to normalize both forms.
+      #
+      # @param user_email [String, Array<String>] email(s) of the user to fetch work for
+      # @param since [Time] start of the time range
+      # @param until_time [Time] end of the time range
+      # @return [Array<WorkItem>] list of work items
+      def fetch(user_email:, since:, until_time:)
+        raise NotImplementedError, "#{self.class} must implement #fetch"
+      end
+
+      # Returns nil for blank strings and placeholder values from .env.example.
+      # Treats values like "your_linear_api_key" or "" as unconfigured.
+      PLACEHOLDER_PATTERN = /\Ayour_/i
+
+      # @param value [String, nil] raw env/config value
+      # @return [String, nil] the value if meaningful, nil otherwise
+      def self.presence(value)
+        return nil if value.nil? || value.strip.empty?
+        return nil if value.match?(PLACEHOLDER_PATTERN)
+
+        value
+      end
+
+      # Reads a credential from the environment, preferring the SNITCHER_-prefixed
+      # name. Applications that embed the gem name their variables
+      # SNITCHER_JIRA_API_TOKEN, SNITCHER_LINEAR_API_KEY and so on, so it is obvious
+      # from the host's .env which library they belong to. The bare name remains
+      # supported — the standalone executables and existing setups rely on it — but
+      # the prefixed one wins, otherwise a stale bare variable would silently shadow
+      # the explicit declaration.
+      #
+      # @param name [String] unprefixed variable name, e.g. "JIRA_API_TOKEN"
+      # @return [String, nil] the configured value, nil when unset or a placeholder
+      def self.env(name)
+        presence(ENV.fetch("SNITCHER_#{name}", nil)) || presence(ENV.fetch(name, nil))
+      end
+
+      private
+
+      # Normalizes the +user_email+ argument (String or Array<String>) into a flat
+      # Array<String>. Sources that can match several addresses at once (e.g. git,
+      # matching commit authors) filter against every entry.
+      # @param user_email [String, Array<String>]
+      # @return [Array<String>]
+      def user_emails(user_email)
+        Array(user_email)
+      end
+
+      # Returns the primary email for sources whose identity is 1:1 (Jira/Linear/ClickUp
+      # resolve one account per user). Extra addresses in a multi-value config are ignored.
+      # @param user_email [String, Array<String>]
+      # @return [String, nil]
+      def primary_email(user_email)
+        Array(user_email).first
+      end
+
+      # Helper to build a WorkItem with the source automatically set.
+      #
+      # @param attributes [Hash] WorkItem attributes (except :source)
+      # @return [WorkItem]
+      def build_work_item(**attributes)
+        WorkItem.new(source: source_name, **attributes)
+      end
+    end
+  end
+end