linear_api 0.3.0

data/lib/linear_api/engine.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module LinearApi
+  class Engine < ::Rails::Engine
+    isolate_namespace LinearApi
+
+    config.generators do |g|
+      g.test_framework :rspec
+      g.fixture_replacement :factory_bot
+      g.factory_bot dir: 'spec/factories'
+    end
+
+    # Load rake tasks
+    rake_tasks do
+      load File.expand_path('../tasks/linear_api.rake', __dir__)
+    end
+
+    initializer 'linear_api.configure' do
+      # Auto-configure from environment variables if not already set
+      LinearApi.api_key ||= ENV['LINEAR_API_KEY']
+      LinearApi.team_id ||= ENV['LINEAR_TEAM_ID']
+    end
+
+    # Eager load models in production
+    config.eager_load_namespaces << LinearApi
+  end
+end

data/lib/linear_api/issue.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module LinearApi
+  # Represents a Linear issue
+  class Issue
+    CREATE_MUTATION = <<~GRAPHQL
+      mutation CreateIssue($input: IssueCreateInput!) {
+        issueCreate(input: $input) {
+          success
+          issue {
+            id
+            identifier
+            title
+            url
+            state {
+              id
+              name
+            }
+          }
+        }
+      }
+    GRAPHQL
+
+    UPDATE_MUTATION = <<~GRAPHQL
+      mutation UpdateIssue($id: String!, $input: IssueUpdateInput!) {
+        issueUpdate(id: $id, input: $input) {
+          success
+          issue {
+            id
+            identifier
+            title
+            state {
+              id
+              name
+            }
+            labels {
+              nodes {
+                id
+                name
+              }
+            }
+          }
+        }
+      }
+    GRAPHQL
+
+    SEARCH_QUERY = <<~GRAPHQL
+      query GetIssue($term: String!) {
+        searchIssues(term: $term, first: 1) {
+          nodes {
+            id
+            identifier
+            title
+            description
+            url
+            priority
+            state {
+              id
+              name
+              type
+            }
+            labels {
+              nodes {
+                id
+                name
+              }
+            }
+            assignee {
+              id
+              name
+            }
+            project {
+              id
+              name
+            }
+            comments {
+              nodes {
+                id
+                body
+                createdAt
+                user {
+                  name
+                }
+              }
+            }
+          }
+        }
+      }
+    GRAPHQL
+
+    LIST_QUERY = <<~GRAPHQL
+      query ListIssues($teamId: String!, $first: Int!) {
+        team(id: $teamId) {
+          issues(first: $first, orderBy: updatedAt) {
+            nodes {
+              id
+              identifier
+              title
+              priority
+              state {
+                id
+                name
+                type
+              }
+              labels {
+                nodes {
+                  id
+                  name
+                }
+              }
+            }
+          }
+        }
+      }
+    GRAPHQL
+
+    ADD_COMMENT_MUTATION = <<~GRAPHQL
+      mutation AddComment($issueId: String!, $body: String!) {
+        commentCreate(input: { issueId: $issueId, body: $body }) {
+          success
+          comment {
+            id
+            body
+            createdAt
+          }
+        }
+      }
+    GRAPHQL
+
+    attr_reader :id, :identifier, :title, :description, :url, :priority,
+                :state, :labels, :assignee, :project, :comments, :raw
+
+    def initialize(data)
+      @raw = data
+      @id = data['id']
+      @identifier = data['identifier']
+      @title = data['title']
+      @description = data['description']
+      @url = data['url']
+      @priority = data['priority']
+      @state = data['state']
+      @labels = (data.dig('labels', 'nodes') || [])
+      @assignee = data['assignee']
+      @project = data['project']
+      @comments = (data.dig('comments', 'nodes') || [])
+    end
+
+    def state_name
+      state&.dig('name')
+    end
+
+    def label_names
+      labels.map { |l| l['name'] }
+    end
+
+    def to_h
+      {
+        id: id,
+        identifier: identifier,
+        title: title,
+        description: description,
+        url: url,
+        priority: priority,
+        state: state_name,
+        labels: label_names
+      }
+    end
+  end
+end

data/lib/linear_api/issue_tracker.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module LinearApi
+  class IssueTracker
+    DEFAULT_LABELS = %i[bug sync].freeze
+    AUTO_TRACKED_PROJECT_NAME = 'Auto-Tracked Errors'
+    AUTO_TRACKED_PROJECT_KEY = 'auto_tracked_errors'
+    AUTO_TRACKED_LABEL_NAME = 'auto:tracked'
+    AUTO_TRACKED_LABEL_COLOR = '#6b7280' # Gray
+
+    class << self
+      # Track an error and create/update a Linear issue
+      #
+      # @param exception [Exception] The exception to track
+      # @param context [Hash] Additional context (date, IDs, etc.)
+      # @param source [Object] The source object (AccountLinking, etc.)
+      # @param labels [Array<Symbol, String>] Labels to apply (:bug, :sync, :critical, or IDs)
+      # @return [LinearApi::Result, LinearApi::SyncedIssue] Result or existing issue
+      def track_error(exception:, context: {}, source: nil, labels: DEFAULT_LABELS)
+        fingerprint = generate_fingerprint(exception, source)
+
+        # Check for existing open issue
+        existing = SyncedIssue.find_open_for_fingerprint(fingerprint)
+        return add_occurrence_comment(existing, exception, context) if existing
+
+        # Ensure auto-tracked project and label exist
+        project_id = ensure_auto_tracked_project
+        auto_label_id = ensure_auto_tracked_label
+
+        # Resolve label IDs from cache + add auto:tracked label
+        label_ids = resolve_label_ids(labels)
+        label_ids << auto_label_id if auto_label_id
+
+        # Create new Linear issue
+        result = LinearApi.client.create_issue(
+          title: build_title(exception),
+          description: build_description(exception, context, source),
+          priority: determine_priority(exception, context),
+          label_ids: label_ids.compact.uniq,
+          project_id: project_id
+        )
+
+        return result unless result.success?
+
+        # Track locally
+        synced_issue = SyncedIssue.create!(
+          linear_id: result.data.id,
+          identifier: result.data.identifier,
+          title: result.data.title,
+          state_name: 'Backlog',
+          priority: determine_priority(exception, context),
+          fingerprint: fingerprint,
+          source_type: source&.class&.name,
+          source_id: source&.id&.to_s,
+          metadata: context.to_json,
+          synced_at: Time.current
+        )
+
+        Result.new(success: true, data: synced_issue)
+      end
+
+      # Track a custom issue (not from exception)
+      def track_issue(title:, description:, context: {}, source: nil, labels: [], priority: 3)
+        fingerprint = generate_custom_fingerprint(title, source)
+
+        existing = SyncedIssue.find_open_for_fingerprint(fingerprint)
+        return Result.new(success: true, data: existing) if existing
+
+        # Ensure auto-tracked project and label exist
+        project_id = ensure_auto_tracked_project
+        auto_label_id = ensure_auto_tracked_label
+
+        # Resolve label IDs + add auto:tracked label
+        label_ids = resolve_label_ids(labels)
+        label_ids << auto_label_id if auto_label_id
+
+        result = LinearApi.client.create_issue(
+          title: "[Auto] #{title}",
+          description: description,
+          priority: priority,
+          label_ids: label_ids.compact.uniq,
+          project_id: project_id
+        )
+
+        return result unless result.success?
+
+        synced_issue = SyncedIssue.create!(
+          linear_id: result.data.id,
+          identifier: result.data.identifier,
+          title: result.data.title,
+          state_name: 'Backlog',
+          priority: priority,
+          fingerprint: fingerprint,
+          source_type: source&.class&.name,
+          source_id: source&.id&.to_s,
+          metadata: context.to_json,
+          synced_at: Time.current
+        )
+
+        Result.new(success: true, data: synced_issue)
+      end
+
+      # Setup auto-tracking infrastructure (project + label)
+      def setup!
+        {
+          project_id: ensure_auto_tracked_project,
+          label_id: ensure_auto_tracked_label
+        }
+      end
+
+      private
+
+      def generate_fingerprint(exception, source = nil)
+        location = exception.backtrace&.first || 'unknown'
+        # Strip Rails root if available
+        location = location.gsub(Rails.root.to_s, '') if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+        base = "#{exception.class}:#{location}"
+        source ? "#{base}:#{source.class}:#{source.id}" : base
+      end
+
+      def generate_custom_fingerprint(title, source = nil)
+        base = Digest::SHA256.hexdigest(title)[0..16]
+        source ? "custom:#{base}:#{source.class}:#{source.id}" : "custom:#{base}"
+      end
+
+      def resolve_label_ids(labels)
+        labels.filter_map { |label| CachedMetadata.resolve_label_id(label) }
+      end
+
+      # Ensure the "Auto-Tracked Errors" project exists
+      def ensure_auto_tracked_project
+        # Check cache first
+        cached = CachedMetadata.projects.find_by(key: AUTO_TRACKED_PROJECT_KEY)
+        return cached.linear_id if cached
+
+        # Check if project exists in Linear
+        result = LinearApi.client.list_projects
+        if result.success?
+          existing = result.data.find { |p| p.name == AUTO_TRACKED_PROJECT_NAME }
+          if existing
+            cache_project(existing)
+            return existing.id
+          end
+        end
+
+        # Create new project
+        create_result = LinearApi.client.create_project(
+          name: AUTO_TRACKED_PROJECT_NAME,
+          description: 'Automatically tracked errors and issues from the application. Do not manually add issues here.',
+          color: '#6b7280'
+        )
+
+        return nil unless create_result.success?
+
+        cache_project(create_result.data)
+        create_result.data.id
+      end
+
+      # Ensure the "auto:tracked" label exists
+      def ensure_auto_tracked_label
+        # Check cache first
+        cached = CachedMetadata.labels.find_by(key: AUTO_TRACKED_LABEL_NAME)
+        return cached.linear_id if cached
+
+        # Check if label exists in Linear
+        result = LinearApi.client.list_labels
+        if result.success?
+          existing = result.data.find { |l| l.name == AUTO_TRACKED_LABEL_NAME }
+          if existing
+            cache_label(existing)
+            return existing.id
+          end
+        end
+
+        # Create new label
+        create_result = LinearApi.client.create_label(
+          name: AUTO_TRACKED_LABEL_NAME,
+          color: AUTO_TRACKED_LABEL_COLOR,
+          description: 'Automatically tracked by LinearApi::IssueTracker'
+        )
+
+        return nil unless create_result.success?
+
+        cache_label(create_result.data)
+        create_result.data.id
+      end
+
+      def cache_project(project)
+        CachedMetadata.upsert_from_api(
+          type: 'project',
+          linear_id: project.id,
+          name: project.name,
+          key: AUTO_TRACKED_PROJECT_KEY,
+          raw_data: project.to_h
+        )
+      end
+
+      def cache_label(label)
+        CachedMetadata.upsert_from_api(
+          type: 'label',
+          linear_id: label.id,
+          name: label.name,
+          key: AUTO_TRACKED_LABEL_NAME,
+          category: 'auto',
+          color: label.color,
+          raw_data: label.to_h
+        )
+      end
+
+      def determine_priority(exception, context)
+        # Priority: 1=Urgent, 2=High, 3=Medium, 4=Low
+        return 1 if context[:critical] || context[:urgent]
+        return 2 if exception.is_a?(ActiveRecord::StatementInvalid)
+        return 2 if context[:high_priority]
+
+        3 # Default to medium
+      end
+
+      def build_title(exception)
+        message = exception.message.to_s.truncate(80)
+        "[Auto] #{exception.class.name.demodulize}: #{message}"
+      end
+
+      def build_description(exception, context, source)
+        <<~MARKDOWN
+          ## Error Details
+
+          **Exception:** `#{exception.class}`
+          **Message:** #{exception.message}
+          **Source:** #{source_description(source)}
+
+          ## Context
+
+          ```json
+          #{JSON.pretty_generate(sanitize_context(context))}
+          ```
+
+          ## Backtrace (first 20 lines)
+
+          ```
+          #{exception.backtrace&.first(20)&.join("\n")}
+          ```
+
+          ---
+          *Auto-created by LinearApi::IssueTracker at #{Time.current.iso8601}*
+        MARKDOWN
+      end
+
+      def source_description(source)
+        return 'N/A' unless source
+
+        "#{source.class.name} ##{source.id}"
+      end
+
+      def sanitize_context(context)
+        context.transform_values do |value|
+          case value
+          when Time, DateTime then value.iso8601
+          when Date then value.to_s
+          when ActiveRecord::Base then "#{value.class.name}##{value.id}"
+          else value
+          end
+        end
+      end
+
+      def add_occurrence_comment(synced_issue, exception, context)
+        comment_body = <<~MARKDOWN
+          ## New Occurrence
+
+          **Time:** #{Time.current.iso8601}
+          **Message:** #{exception.message}
+
+          ### Context
+
+          ```json
+          #{JSON.pretty_generate(sanitize_context(context))}
+          ```
+        MARKDOWN
+
+        LinearApi.client.add_comment(
+          issue_id: synced_issue.linear_id,
+          body: comment_body
+        )
+
+        synced_issue.update!(synced_at: Time.current)
+
+        Result.new(success: true, data: synced_issue)
+      end
+    end
+  end
+end

data/lib/linear_api/label.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module LinearApi
+  # Represents a Linear label
+  class Label
+    LIST_QUERY = <<~GRAPHQL
+      query ListLabels($teamId: String!) {
+        team(id: $teamId) {
+          labels {
+            nodes {
+              id
+              name
+              color
+              description
+            }
+          }
+        }
+      }
+    GRAPHQL
+
+    attr_reader :id, :name, :color, :description, :raw
+
+    def initialize(data)
+      @raw = data
+      @id = data['id']
+      @name = data['name']
+      @color = data['color']
+      @description = data['description']
+    end
+
+    def to_h
+      {
+        id: id,
+        name: name,
+        color: color,
+        description: description
+      }
+    end
+  end
+end

data/lib/linear_api/project.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module LinearApi
+  # Represents a Linear project (epic)
+  class Project
+    LIST_QUERY = <<~GRAPHQL
+      query ListProjects($teamId: String!) {
+        team(id: $teamId) {
+          projects {
+            nodes {
+              id
+              name
+              description
+              state
+              progress
+            }
+          }
+        }
+      }
+    GRAPHQL
+
+    attr_reader :id, :name, :description, :state, :progress, :raw
+
+    def initialize(data)
+      @raw = data
+      @id = data['id']
+      @name = data['name']
+      @description = data['description']
+      @state = data['state']
+      @progress = data['progress']
+    end
+
+    def to_h
+      {
+        id: id,
+        name: name,
+        description: description,
+        state: state,
+        progress: progress
+      }
+    end
+  end
+end

data/lib/linear_api/result.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module LinearApi
+  # Result object for API operations
+  class Result
+    attr_reader :data, :error, :raw_response
+
+    def initialize(success:, data: nil, error: nil, raw_response: nil)
+      @success = success
+      @data = data
+      @error = error
+      @raw_response = raw_response
+    end
+
+    def success?
+      @success
+    end
+
+    def failure?
+      !@success
+    end
+
+    # Allow accessing data directly on result
+    def method_missing(method, *args, &block)
+      if data.respond_to?(method)
+        data.public_send(method, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      data.respond_to?(method, include_private) || super
+    end
+  end
+end

data/lib/linear_api/team.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module LinearApi
+  # Represents a Linear team
+  class Team
+    GET_QUERY = <<~GRAPHQL
+      query GetTeam($teamId: String!) {
+        team(id: $teamId) {
+          id
+          name
+          key
+          description
+        }
+      }
+    GRAPHQL
+
+    STATES_QUERY = <<~GRAPHQL
+      query GetStates($teamId: String!) {
+        team(id: $teamId) {
+          states {
+            nodes {
+              id
+              name
+              type
+              position
+            }
+          }
+        }
+      }
+    GRAPHQL
+
+    attr_reader :id, :name, :key, :description, :raw
+
+    def initialize(data)
+      @raw = data
+      @id = data['id']
+      @name = data['name']
+      @key = data['key']
+      @description = data['description']
+    end
+
+    def to_h
+      {
+        id: id,
+        name: name,
+        key: key,
+        description: description
+      }
+    end
+  end
+end

data/lib/linear_api/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LinearApi
+  VERSION = '0.3.0'
+end

data/lib/linear_api.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'linear_api/version'
+require_relative 'linear_api/client'
+require_relative 'linear_api/result'
+require_relative 'linear_api/issue'
+require_relative 'linear_api/project'
+require_relative 'linear_api/label'
+require_relative 'linear_api/team'
+
+# Load Rails engine and services if Rails is present
+if defined?(Rails::Engine)
+  require_relative 'linear_api/engine'
+  require_relative 'linear_api/cache_sync'
+  require_relative 'linear_api/issue_tracker'
+end
+
+module LinearApi
+  class Error < StandardError; end
+  class AuthenticationError < Error; end
+  class NotFoundError < Error; end
+  class RateLimitError < Error; end
+
+  class << self
+    attr_accessor :api_key, :team_id
+
+    def configure
+      yield self
+    end
+
+    def client
+      raise AuthenticationError, 'API key not configured' unless api_key
+
+      @client ||= Client.new(api_key: api_key, team_id: team_id)
+    end
+
+    def reset_client!
+      @client = nil
+    end
+  end
+end