archsight 0.1.2 → 0.1.3

data/lib/archsight/import/handlers/jira_base.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "cgi"
+
+require_relative "../handler"
+
+# Shared module for Jira handlers
+#
+# Provides common functionality for Jira API interactions including:
+# - HTTP client with Bearer token authentication
+# - User lookup and caching (email -> Jira username)
+# - Project info lookup and caching
+# - Team loading and email extraction
+# - Rate limiting
+module Archsight::Import::Handlers::JiraBase
+  # Initialize Jira client
+  # @param host [String] Jira host (e.g., "hosting-jira.1and1.org")
+  # @param token [String] Jira Bearer token
+  # @param rate_limit_ms [Integer] Rate limit delay in milliseconds
+  def init_jira_client(host:, token:, rate_limit_ms: 100)
+    @jira_host = host
+    @jira_token = token
+    @rate_limit_ms = rate_limit_ms
+    @jira_uri = URI("https://#{host}")
+    @jira_http = Net::HTTP.new(@jira_uri.host, @jira_uri.port)
+    @jira_http.use_ssl = true
+    @jira_http.read_timeout = 120
+    @user_cache = {}
+    @project_cache = {}
+  end
+
+  # Make a GET request to the Jira API
+  # @param path [String] API path (e.g., "/rest/api/2/myself")
+  # @return [Hash, Array] Parsed JSON response
+  # @raise [RuntimeError] on HTTP errors
+  def jira_get(path)
+    request = Net::HTTP::Get.new(path)
+    request["Authorization"] = "Bearer #{@jira_token}"
+    request["Content-Type"] = "application/json"
+    response = @jira_http.request(request)
+
+    raise "Jira API error: #{response.code} #{response.message}" unless response.is_a?(Net::HTTPSuccess)
+
+    JSON.parse(response.body)
+  end
+
+  # Verify Jira credentials by calling /rest/api/2/myself
+  # @return [Hash] User info from Jira
+  # @raise [RuntimeError] on authentication failure
+  def verify_jira_credentials
+    progress.update("Verifying Jira credentials...")
+    user = jira_get("/rest/api/2/myself")
+    progress.update("Authenticated as #{user["displayName"] || user["name"]}")
+    user
+  rescue StandardError => e
+    raise "Jira authentication failed: #{e.message}"
+  end
+
+  # Find Jira usernames for a list of email addresses
+  # @param emails [Array<String>] Email addresses to look up
+  # @return [Array<String>] Jira usernames
+  def find_jira_users(emails)
+    users = []
+
+    emails.each do |email|
+      # Check cache first
+      if @user_cache.key?(email)
+        users << @user_cache[email] if @user_cache[email]
+        next
+      end
+
+      rate_limit
+      begin
+        result = jira_get("/rest/api/2/user/search?username=#{CGI.escape(email)}&maxResults=1")
+
+        if result&.any?
+          user = result.first
+          username = user["name"] || user["accountId"]
+          @user_cache[email] = username
+          users << username
+        else
+          @user_cache[email] = nil
+        end
+      rescue StandardError => e
+        progress.warn("Error searching for user #{email}: #{e.message}")
+        @user_cache[email] = nil
+      end
+    end
+
+    users.compact.uniq
+  end
+
+  # Get project info from Jira API
+  # @param project_key [String] Project key
+  # @return [Hash, nil] Project info or nil if not found
+  def get_project_info(project_key)
+    return @project_cache[project_key] if @project_cache.key?(project_key)
+
+    rate_limit
+    begin
+      project = jira_get("/rest/api/2/project/#{project_key}")
+      @project_cache[project_key] = project
+      project
+    rescue StandardError => e
+      progress.warn("Error fetching project #{project_key}: #{e.message}")
+      @project_cache[project_key] = nil
+      nil
+    end
+  end
+
+  # Extract email addresses from a team's annotations
+  # @param team [Archsight::Resources::Base] Team resource
+  # @return [Array<String>] Unique email addresses
+  def extract_team_emails(team)
+    emails = []
+
+    if (lead = team.annotations["team/lead"])
+      email = extract_email(lead)
+      emails << email if email
+    end
+
+    if (members = team.annotations["team/members"])
+      members.each_line do |line|
+        line = line.strip
+        next if line.empty?
+
+        email = extract_email(line)
+        emails << email if email
+      end
+    end
+
+    emails.compact.uniq
+  end
+
+  # Load teams from database with optional filter
+  # @param ignored_teams [Array<String>] Team names to ignore
+  # @param require_jira [Boolean] If true, only return teams WITH team/jira
+  # @param require_no_jira [Boolean] If true, only return teams WITHOUT team/jira
+  # @return [Array<Archsight::Resources::Base>] Filtered and sorted teams
+  def load_teams(ignored_teams: [], require_jira: false, require_no_jira: false)
+    teams = database.instances_by_kind("BusinessActor")
+
+    filtered = teams.values.reject do |team|
+      next true if ignored_teams.include?(team.name)
+      next true if extract_team_emails(team).empty?
+
+      jira_project = team.annotations["team/jira"]
+      has_jira = jira_project && !jira_project.empty?
+
+      next true if require_jira && !has_jira
+      next true if require_no_jira && has_jira
+
+      false
+    end
+
+    filtered.sort_by(&:name)
+  end
+
+  # Parse comma-separated config values
+  # @param value [String, nil] Comma-separated values
+  # @return [Array<String>] Parsed array
+  def parse_list_config(value)
+    return [] if value.nil? || value.empty?
+
+    value.split(",").map(&:strip)
+  end
+
+  # Apply rate limiting between API calls
+  def rate_limit
+    sleep(@rate_limit_ms / 1000.0)
+  end
+
+  private
+
+  # Extract email from a member string
+  # Handles formats like "Name <email@example.com>" or "email@example.com"
+  # @param member_str [String] Member string
+  # @return [String, nil] Extracted email or nil
+  def extract_email(member_str)
+    if member_str =~ /<([^>]+)>/
+      Regexp.last_match(1).strip.downcase
+    elsif member_str =~ /@/
+      member_str.strip.downcase
+    end
+  end
+end

data/lib/archsight/import/handlers/jira_discover.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require_relative "../handler"
+require_relative "../registry"
+require_relative "jira_base"
+
+# Jira Discover handler - discovers Jira projects for teams without team/jira set
+#
+# Configuration:
+#   import/config/host - Jira host (required, e.g., "hosting-jira.1and1.org")
+#   import/config/minActivityThreshold - Minimum issues for valid project (default: 5)
+#   import/config/excludedProjectCategories - Comma-separated category IDs to exclude
+#   import/config/excludedProjects - Comma-separated project keys to exclude
+#   import/config/ignoredTeams - Comma-separated team names to skip
+#   import/config/rateLimitMs - API rate limit delay (default: 100)
+#
+# Environment:
+#   JIRA_TOKEN - Jira Personal Access Token (required)
+#
+# Output:
+#   BusinessActor patches with team/jira annotation
+class Archsight::Import::Handlers::JiraDiscover < Archsight::Import::Handler
+  include Archsight::Import::Handlers::JiraBase
+
+  def execute
+    load_configuration
+    verify_jira_credentials
+    discover_projects
+
+    write_generates_meta
+  end
+
+  private
+
+  def load_configuration
+    @host = config("host")
+    raise "Missing required config: host" unless @host
+
+    @token = ENV.fetch("JIRA_TOKEN", nil)
+    raise "Missing required environment variable: JIRA_TOKEN" unless @token
+
+    @min_activity_threshold = config("minActivityThreshold", default: "5").to_i
+    @excluded_project_categories = parse_list_config(config("excludedProjectCategories"))
+    @excluded_projects = parse_list_config(config("excludedProjects"))
+    @ignored_teams = parse_list_config(config("ignoredTeams"))
+    @rate_limit_ms = config("rateLimitMs", default: "100").to_i
+
+    init_jira_client(host: @host, token: @token, rate_limit_ms: @rate_limit_ms)
+  end
+
+  def discover_projects
+    teams = load_teams(ignored_teams: @ignored_teams, require_no_jira: true)
+
+    if teams.empty?
+      progress.warn("No teams found without Jira project configured")
+      # Still write self-marker for caching
+      write_yaml(YAML.dump(self_marker))
+      return
+    end
+
+    progress.update("Found #{teams.size} teams without Jira project configured")
+
+    documents = []
+    discovered_count = 0
+
+    teams.each_with_index do |team, idx|
+      emails = extract_team_emails(team)
+      progress.update("[#{idx + 1}/#{teams.size}] Processing #{team.name}...")
+
+      project_key = discover_team_project(team.name, emails)
+
+      next unless project_key
+
+      project_info = get_project_info(project_key)
+      project_name = project_info&.dig("name") || ""
+
+      documents << {
+        "apiVersion" => "architecture/v1alpha1",
+        "kind" => "BusinessActor",
+        "metadata" => {
+          "name" => team.name,
+          "annotations" => {
+            "team/jira" => project_key,
+            "generated/script" => import_resource.name,
+            "generated/at" => Time.now.utc.iso8601
+          }
+        }
+      }
+      discovered_count += 1
+      progress.update("[#{idx + 1}/#{teams.size}] #{team.name} -> #{project_key} (#{project_name})")
+    end
+
+    # Add self-marker for caching
+    documents << self_marker
+
+    if documents.size > 1
+      yaml_content = documents.map { |doc| YAML.dump(doc) }.join("\n")
+      write_yaml(yaml_content)
+      progress.complete("Discovered Jira projects for #{discovered_count}/#{teams.size} teams")
+    else
+      # Still write self-marker even if no projects discovered
+      write_yaml(YAML.dump(self_marker))
+      progress.complete("No Jira projects discovered for #{teams.size} teams")
+    end
+  end
+
+  def discover_team_project(team_name, emails)
+    jira_users = find_jira_users(emails)
+    return nil if jira_users.empty?
+
+    project_activity = Hash.new(0)
+
+    # Build JQL to find issues where team members are assignee or reporter
+    user_list = jira_users.map { |u| "\"#{u}\"" }.join(", ")
+    jql = "(assignee IN (#{user_list}) OR reporter IN (#{user_list})) AND updated >= -26w"
+
+    rate_limit
+    begin
+      # Get issues to count by project
+      result = jira_get("/rest/api/2/search?jql=#{CGI.escape(jql)}&maxResults=500&fields=project")
+      issues = result["issues"] || []
+      issues.each do |issue|
+        project_key = issue.dig("fields", "project", "key")
+        project_activity[project_key] += 1 if project_key
+      end
+    rescue StandardError => e
+      progress.warn("Error querying issues for #{team_name}: #{e.message}")
+      return nil
+    end
+
+    return nil if project_activity.empty?
+
+    # Filter out excluded project categories and find project with most activity
+    sorted_projects = project_activity.sort_by { |_, count| -count }
+
+    sorted_projects.each do |project_key, count|
+      next if excluded_project?(project_key)
+      next if count < @min_activity_threshold
+
+      return project_key
+    end
+
+    nil
+  end
+
+  def excluded_project?(project_key)
+    # Check if project key is explicitly excluded
+    return true if @excluded_projects.include?(project_key)
+
+    # Check if project category is excluded
+    return false if @excluded_project_categories.empty?
+
+    project_info = get_project_info(project_key)
+    return false unless project_info
+
+    category_id = project_info.dig("projectCategory", "id")&.to_s
+    @excluded_project_categories.include?(category_id)
+  end
+end
+
+Archsight::Import::Registry.register("jira-discover", Archsight::Import::Handlers::JiraDiscover)

data/lib/archsight/import/handlers/jira_metrics.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "../handler"
+require_relative "../registry"
+require_relative "jira_base"
+
+# Jira Metrics handler - exports per-month issue metrics for teams with team/jira set
+#
+# Configuration:
+#   import/config/host - Jira host (required, e.g., "hosting-jira.1and1.org")
+#   import/config/monthsToAnalyze - Number of months for metrics (default: 6)
+#   import/config/ignoredTeams - Comma-separated team names to skip
+#   import/config/rateLimitMs - API rate limit delay (default: 100)
+#
+# Environment:
+#   JIRA_TOKEN - Jira Personal Access Token (required)
+#
+# Output:
+#   BusinessActor patches with jira/issues/created, jira/issues/resolved annotations
+class Archsight::Import::Handlers::JiraMetrics < Archsight::Import::Handler
+  include Archsight::Import::Handlers::JiraBase
+
+  def execute
+    load_configuration
+    verify_jira_credentials
+    export_metrics
+
+    write_generates_meta
+  end
+
+  private
+
+  def load_configuration
+    @host = config("host")
+    raise "Missing required config: host" unless @host
+
+    @token = ENV.fetch("JIRA_TOKEN", nil)
+    raise "Missing required environment variable: JIRA_TOKEN" unless @token
+
+    @months_to_analyze = config("monthsToAnalyze", default: "6").to_i
+    @ignored_teams = parse_list_config(config("ignoredTeams"))
+    @rate_limit_ms = config("rateLimitMs", default: "100").to_i
+
+    init_jira_client(host: @host, token: @token, rate_limit_ms: @rate_limit_ms)
+  end
+
+  def export_metrics
+    teams = load_teams(ignored_teams: @ignored_teams, require_jira: true)
+
+    if teams.empty?
+      progress.warn("No teams found with Jira project configured")
+      write_yaml(YAML.dump(self_marker))
+      return
+    end
+
+    progress.update("Found #{teams.size} teams with Jira project configured")
+    progress.update("Collecting metrics for the last #{@months_to_analyze} months...")
+
+    documents = teams.each_with_index.filter_map do |team, idx|
+      process_team_metrics(team, idx, teams.size)
+    end
+
+    write_metrics_output(documents, teams.size)
+  end
+
+  def process_team_metrics(team, idx, total)
+    project_key = team.annotations["team/jira"]
+    primary_key = project_key.split(/[,\n]/).first&.strip
+    emails = extract_team_emails(team)
+
+    progress.update("[#{idx + 1}/#{total}] #{team.name} (#{primary_key})...")
+
+    metrics = collect_team_metrics(primary_key, emails)
+
+    if metrics[:created].all?(&:zero?) && metrics[:resolved].all?(&:zero?)
+      progress.update("[#{idx + 1}/#{total}] #{team.name} (#{primary_key}) - no activity")
+      return nil
+    end
+
+    log_metrics_summary(team, idx, total, metrics)
+    build_metrics_document(team, metrics)
+  end
+
+  def log_metrics_summary(team, idx, total, metrics)
+    created_total = metrics[:created].sum
+    resolved_total = metrics[:resolved].sum
+    progress.update("[#{idx + 1}/#{total}] #{team.name} - #{created_total} created, #{resolved_total} resolved")
+  end
+
+  def build_metrics_document(team, metrics)
+    {
+      "apiVersion" => "architecture/v1alpha1",
+      "kind" => "BusinessActor",
+      "metadata" => {
+        "name" => team.name,
+        "annotations" => {
+          "jira/issues/created" => metrics[:created].join(","),
+          "jira/issues/resolved" => metrics[:resolved].join(","),
+          "generated/script" => import_resource.name,
+          "generated/at" => Time.now.utc.iso8601
+        }
+      }
+    }
+  end
+
+  def write_metrics_output(documents, teams_size)
+    documents << self_marker
+
+    if documents.size > 1
+      yaml_content = documents.map { |doc| YAML.dump(doc) }.join("\n")
+      write_yaml(yaml_content)
+      progress.complete("Collected metrics for #{documents.size - 1} teams")
+    else
+      write_yaml(YAML.dump(self_marker))
+      progress.complete("No metrics collected for #{teams_size} teams")
+    end
+  end
+
+  def collect_team_metrics(project_key, emails)
+    jira_users = find_jira_users(emails)
+
+    created_counts = []
+    resolved_counts = []
+
+    # Generate month ranges for the last N months
+    months = generate_month_ranges(@months_to_analyze)
+
+    months.each do |month_start, month_end|
+      created = count_issues(project_key, jira_users, "created", month_start, month_end)
+      resolved = count_issues(project_key, jira_users, "resolved", month_start, month_end)
+
+      created_counts << created
+      resolved_counts << resolved
+    end
+
+    { created: created_counts, resolved: resolved_counts }
+  end
+
+  def generate_month_ranges(num_months)
+    ranges = []
+    today = Date.today
+
+    num_months.times do |i|
+      # Go back i+1 months (we don't include current incomplete month)
+      month_date = today << (num_months - i)
+      month_start = Date.new(month_date.year, month_date.month, 1)
+      month_end = (month_start >> 1) - 1 # Last day of month
+
+      ranges << [month_start, month_end]
+    end
+
+    ranges
+  end
+
+  def count_issues(project_key, jira_users, date_field, start_date, end_date)
+    return 0 if jira_users.empty?
+
+    user_list = jira_users.map { |u| "\"#{u}\"" }.join(", ")
+
+    # Build JQL for team members in the date range
+    jql = "project = #{project_key} AND " \
+          "(assignee IN (#{user_list}) OR reporter IN (#{user_list})) AND " \
+          "#{date_field} >= #{start_date.strftime("%Y-%m-%d")} AND " \
+          "#{date_field} <= #{end_date.strftime("%Y-%m-%d")}"
+
+    rate_limit
+    begin
+      # Use maxResults=0 to just get the count
+      result = jira_get("/rest/api/2/search?jql=#{CGI.escape(jql)}&maxResults=0")
+      result["total"] || 0
+    rescue StandardError => e
+      progress.warn("Error counting #{date_field} issues: #{e.message}")
+      0
+    end
+  end
+end
+
+Archsight::Import::Registry.register("jira-metrics", Archsight::Import::Handlers::JiraMetrics)