RHIDP-8354: Implement logic to load Jira issue by configuration (#1389)

* feat(scorecard): implement logic to load Jira issue by configuration

Signed-off-by: Ihor Mykhno <imykhno@redhat.com>

* refactor(scorecard): move jira integration constants from scorecard-common to the plugin folder

Signed-off-by: Ihor Mykhno <imykhno@redhat.com>

* refactor(scorecard): logic for Jira integration

Signed-off-by: Ihor Mykhno <imykhno@redhat.com>

* refactor(scorecard): preparing jira request logic

Signed-off-by: Ihor Mykhno <imykhno@redhat.com>

* feat(scorecard): add configuration steps to README.md for jira integration

Signed-off-by: Ihor Mykhno <imykhno@redhat.com>

* fix(scorecard): jira integration

---------

Signed-off-by: Ihor Mykhno <imykhno@redhat.com>

Author: imykhno

workspaces/scorecard/plugins/scorecard-backend-module-jira/README.md

@@ -1,5 +1,155 @@
-# @@red-hat-developer-hub/backstage-plugin-scorecard-backend-module-jira
+# Scorecard Backend Module for Jira
 
-The jira backend module for the scorecard plugin.
+This is an extension module to the `backstage-plugin-scorecard-backend` plugin. It provides Jira-specific metrics for software components registered in the Backstage catalog.
 
-_This plugin was created through the Backstage CLI_
+## Prerequisites
+
+Before installing this module, ensure that the Scorecard backend plugin is integrated into your Backstage instance. Follow the [Scorecard backend plugin README](../scorecard-backend/README.md) for setup instructions.
+
+This module also requires a Jira integration to be configured in your `app-config.yaml`. The following example of configuration can help:
+
+**Configuration `token`:**
+
+- For the `cloud` product:
+
+  - Obtain your personal token from Jira
+  - Create a Base64-encoded string from the following plain text format: `your-atlassian-email:your-jira-api-token`:
+
+  ```bash
+  // Node
+  new Buffer('your-atlassian-email:your-jira-api-token').toString(
+    'base64',
+  );
+
+  // Browser console
+  btoa('your-atlassian-email:your-jira-api-token');
+
+  // Bash
+  echo -n 'your-atlassian-email:your-jira-api-token' | base64
+  ```
+
+- For the `datacenter` product:
+  - Obtain your personal token from Jira
+  - Use the Jira token without changing
+
+```yaml
+jira:
+  # Required
+  baseUrl: ${JIRA_URL}
+  # Required
+  token: ${JIRA_TOKEN}
+  # Required: Supported products: `cloud` or `datacenter`
+  product: cloud
+  # By default, the latest version is used. You can omit this prop when using the latest version.
+  apiVersion: '3'
+```
+
+## Installation
+
+To install this backend module:
+
+```bash
+# From your root directory
+yarn workspace backend add @red-hat-developer-hub/backstage-plugin-scorecard-backend-module-jira
+```
+
+```ts
+// packages/backend/src/index.ts
+import { createBackend } from '@backstage/backend-defaults';
+
+const backend = createBackend();
+
+// Scorecard backend plugin
+backend.add(
+  import('@red-hat-developer-hub/backstage-plugin-scorecard-backend'),
+);
+
+// Install the Jira module
+/* highlight-add-next-line */
+backend.add(
+  import(
+    '@red-hat-developer-hub/backstage-plugin-scorecard-backend-module-jira'
+  ),
+);
+
+backend.start();
+```
+
+### Entity Annotations
+
+For the Jira metrics to work, your catalog entities must have the required Jira annotations:
+
+```yaml
+# catalog-info.yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-service
+  annotations:
+    # Required: Jira project key
+    jira/project-key: PROJECT
+    # Optional: Jira component name
+    jira/component: Component
+    # Optional: Jira label
+    jira/label: UI
+    # Optional: recommended to use Jira team ID instead of team title
+    jira/team: 9d3ea319-fb5b-4621-9dab-05fe502283e
+    # Optional: Custom filters for loading data request. This filter replaces customFilters form app-config.yaml
+    jira/custom-filter: 'reporter = "psycon98@yahoo.com" AND resolution is not EMPTY'
+spec:
+  type: website
+  lifecycle: experimental
+  owner: guests
+  system: examples
+  providesApis: [example-grpc-api]
+```
+
+## Available Metrics
+
+### Jira Issues (`jira.open_issues`)
+
+This metric counts all jira issues that match the filter condition specified in annotation and app-config.yaml
+
+- **Metric ID**: `jira.open_issues`
+- **Type**: `Number`
+- **Datasource**: `jira`
+- **Default thresholds**:
+
+```yaml
+# app-config.yaml
+scorecard:
+plugins:
+  jira:
+    open_issues:
+      thresholds:
+        rules:
+          - key: success
+            expression: '<=50'
+          - key: warning
+            expression: '>50'
+          - key: error
+            expression: '>100'
+```
+
+## Configuration
+
+### Threshold Configuration
+
+Thresholds define conditions that determine which category a metric value belongs to ( `error`, `warning`, or `success`). You can configure custom thresholds for the Jira metrics. Check out detailed explanation of [threshold configuration](../scorecard-backend/docs/thresholds.md).
+
+### Options Configuration
+
+Options define configuration that affect fetch jira issues global configuration, but all options are optional. This settings are closely related with annotation settings and whole jira issues loading process.
+
+```yaml
+# app-config.yaml
+scorecard:
+plugins:
+  jira:
+    open_issues:
+      options:
+        # Optional: use mandatoryFilter filter if need to replaces default which is "type = Bug AND resolution = Unresolved"
+        mandatoryFilter: Type = Task AND Resolution = Resolved
+        # Optional: use to specify global customFilter, however the annotation `jira/custom-filter` will replaces them
+        customFilter: priority in ("Critical", "Blocker")
+```

workspaces/scorecard/plugins/scorecard-backend-module-jira/config.d.ts

@@ -15,13 +15,24 @@
  */
 
 export interface Config {
+  /** Configuration for jira plugin */
+  jira: {
+    baseUrl: string;
+    token: string;
+    product: string;
+    apiVersion?: string;
+  };
   /** Configuration for scorecard plugin */
   scorecard?: {
     /** Configuration for scorecard plugins/datasources */
     plugins?: {
       /** JIRA datasource configuration */
       jira?: {
         open_issues?: {
+          options?: {
+            mandatoryFilter?: string;
+            customFilter?: string;
+          };
           thresholds?: {
             rules?: Array<{
               key: 'error' | 'warning' | 'success';

workspaces/scorecard/plugins/scorecard-backend-module-jira/src/annotations.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export enum ScorecardJiraAnnotations {
+  PROJECT_KEY = 'jira/project-key',
+  COMPONENT = 'jira/component',
+  LABEL = 'jira/label',
+  TEAM = 'jira/team',
+  CUSTOM_FILTER = 'jira/custom-filter',
+}

workspaces/scorecard/plugins/scorecard-backend-module-jira/src/clients/JiraClientFactory.test.ts

@@ -0,0 +1,78 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Config } from '@backstage/config';
+import { mockServices } from '@backstage/backend-test-utils';
+import { JiraDataCenterClient } from '../clients/JiraDataCenterClient';
+import { JiraClientFactory } from './JiraClientFactory';
+import { JiraCloudClient } from '../clients/JiraCloudClient';
+
+jest.mock('../clients/JiraDataCenterClient');
+jest.mock('../clients/JiraCloudClient');
+
+const getConfig = (product: string) => {
+  return mockServices.rootConfig({
+    data: {
+      jira: {
+        product,
+      },
+    },
+  });
+};
+
+describe('JiraClientFactory', () => {
+  let config: Config;
+
+  beforeEach(() => {
+    config = getConfig('datacenter');
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('when product is datacenter', () => {
+    it('should create a JiraDataCenterClient', () => {
+      const client = JiraClientFactory.create(config);
+      expect(JiraDataCenterClient).toHaveBeenCalledWith(config);
+      expect(client).toBeInstanceOf(JiraDataCenterClient);
+    });
+  });
+
+  describe('when product is cloud', () => {
+    beforeEach(() => {
+      config = getConfig('cloud');
+    });
+
+    it('should create a JiraCloudClient', () => {
+      const client = JiraClientFactory.create(config);
+      expect(JiraCloudClient).toHaveBeenCalledWith(config);
+      expect(client).toBeInstanceOf(JiraCloudClient);
+    });
+  });
+
+  describe('when product is invalid', () => {
+    beforeEach(() => {
+      config = getConfig('foo');
+    });
+
+    it('should throw an error', () => {
+      expect(() => JiraClientFactory.create(config)).toThrow(
+        "Invalid Jira product: foo. Valid products for 'jira.product' are: datacenter, cloud",
+      );
+    });
+  });
+});

workspaces/scorecard/plugins/scorecard-backend-module-jira/src/clients/JiraClientFactory.ts

@@ -0,0 +1,39 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Config } from '@backstage/config';
+import { JIRA_CONFIG_PATH } from '../constants';
+import { JiraClient } from '../clients/base';
+import { JiraDataCenterClient } from '../clients/JiraDataCenterClient';
+import { JiraCloudClient } from '../clients/JiraCloudClient';
+
+export class JiraClientFactory {
+  static create(config: Config): JiraClient {
+    const jiraConfig = config.getConfig(JIRA_CONFIG_PATH);
+    const product = jiraConfig.getString('product');
+
+    switch (product) {
+      case 'datacenter':
+        return new JiraDataCenterClient(config);
+      case 'cloud':
+        return new JiraCloudClient(config);
+      default:
+        throw new Error(
+          `Invalid Jira product: ${product}. Valid products for 'jira.product' are: datacenter, cloud`,
+        );
+    }
+  }
+}