feat(#94): add support for JIRA issues (#123)

Author: scastlara

README.md

@@ -141,9 +141,10 @@ lgtm-ai can enhance code reviews by including context from linked issues or user
 
 - Provide the following options to the `lgtm review` command:
   - `--issues-url`: The base URL of the issues or user story page.
-  - `--issues-source`: The platform for the issues (e.g., `github`, `gitlab`).
+  - `--issues-source`: The platform for the issues (e.g., `github`, `gitlab`, `jira`).
   - `--issues-regex`: (Optional) A regex pattern to extract the issue ID from the PR title or description.
   - `--issues-api-key`: (Optional) API key for the issues service (if different from `--git-api-key`).
+  - `--issues-user`: (Optional) Username for the issues service (required if source is `jira`).
 
 **Example:**
 ```sh
@@ -161,7 +162,7 @@ lgtm review \
 
 **Notes:**
 
-- Only GitHub and GitLab issues are supported for now.
+- GitHub, GitLab, and [JIRA cloud](https://developer.atlassian.com/cloud/jira/platform/) issues are supported.
 - If `--issues-api-key` is not provided, lgtm will use `--git-api-key` for authentication.
 - If no issue is found, the review will proceed without issue context.
 - lgtm provides a default regex for extracting issue IDs that works with [conventional commits](https://www.conventionalcommits.org). This means you often do not need to specify `--issues-regex` if your PR titles or commit messages follow the conventional commit format (e.g., `feat(#123): add new feature`), or if your PR descriptions contain mentions to issues like: `refs: #123` or `closes: #123`.
@@ -392,6 +393,7 @@ When it comes to preference for selecting options, lgtm follows this preference
 | issues_source        | Issues Integration   | 🟡 Conditionally required     | Required if `issues_url` is set.                                                 |
 | issues_regex         | Issues Integration   | 🟢 Optional                   | Regex for issue ID extraction. Defaults to conventional commit compatible regex. |
 | issues_api_key       | Issues Integration   | 🟢 Optional                   | API key for issues service (if different from `git_api_key`). Can't be given through config file. Also available through env variable `LGTM_ISSUES_API_KEY`.                         |
+| issues_user       | Issues Integration   | 🟡 Conditionally required    | Username for accessing issues information. Only required for `issues_source=jira` |
 
 </details>
 
@@ -423,9 +425,10 @@ These options are only used when performing reviews through the command `lgtm re
 See [Using Issue/User Story Information section](#using-issueuser-story-information).
 
 - **issues_url**: The base URL of the issues or user story page to fetch additional context for the PR. If set, `issues_source` becomes required.
-- **issues_source**: The platform for the issues (e.g., `github`, `gitlab`). Required if `issues_url` is set.
+- **issues_source**: The platform for the issues (e.g., `github`, `gitlab`, `jira`). Required if `issues_url` is set.
 - **issues_regex**: A regex pattern to extract the issue ID from the PR title or description. If omitted, lgtm uses a default regex compatible with conventional commits and common PR formats.
 - **issues_api_key**: API key for the issues service (if different from `git_api_key`). Can be given as a CLI argument, or as an environment variable (`LGTM_ISSUES_API_KEY`).
+- **issues_user**: Username for accessing the issues service (only necessary for `jira`). Can be given as a CLI argument, or as an environment variable (`LGTM_ISSUES_USER`).
 
 #### Example `lgtm.toml`
 

src/lgtm_ai/__main__.py

@@ -13,6 +13,7 @@
     get_summarizing_agent_with_settings,
 )
 from lgtm_ai.ai.schemas import AgentSettings, CommentCategory, SupportedAIModels, SupportedAIModelsList
+from lgtm_ai.base.constants import DEFAULT_HTTPX_TIMEOUT
 from lgtm_ai.base.schemas import IntOrNoLimit, IssuesSource, OutputFormat, PRUrl
 from lgtm_ai.base.utils import git_source_supports_multiline_suggestions
 from lgtm_ai.config.constants import DEFAULT_INPUT_TOKEN_LIMIT
@@ -23,6 +24,7 @@
 from lgtm_ai.formatters.pretty import PrettyFormatter
 from lgtm_ai.git_client.base import GitClient
 from lgtm_ai.git_client.utils import get_git_client
+from lgtm_ai.jira.jira import JiraIssuesClient
 from lgtm_ai.review import CodeReviewer
 from lgtm_ai.review.context import ContextRetriever, IssuesClient
 from lgtm_ai.review.guide import ReviewGuideGenerator
@@ -117,6 +119,10 @@ def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
     "--issues-api-key",
     help="The optional API key to the issues service (Jira, GitLab, GitHub, etc.). If using GitHub or GitLab and not provided, `--git-api-key` will be used instead.",
 )
+@click.option(
+    "--issues-user",
+    help="The username to download issues information (only needed for Jira). Required if `--issues-source` is `jira`.",
+)
 @click.option(
     "--technologies",
     multiple=True,
@@ -148,6 +154,7 @@ def review(
     issues_regex: str | None,
     issues_source: IssuesSource | None,
     issues_api_key: str | None,
+    issues_user: str | None,
 ) -> None:
     """Review a Pull Request using AI."""
     _set_logging_level(logger, verbose)
@@ -173,6 +180,7 @@ def review(
             issues_regex=issues_regex,
             issues_source=issues_source,
             issues_api_key=issues_api_key,
+            issues_user=issues_user,
         ),
         config_file=config,
     ).resolve_config()
@@ -190,7 +198,7 @@ def review(
             model_name=resolved_config.model, api_key=resolved_config.ai_api_key, model_url=resolved_config.model_url
         ),
         context_retriever=ContextRetriever(
-            git_client=git_client, issues_client=issues_client, httpx_client=httpx.Client(timeout=3)
+            git_client=git_client, issues_client=issues_client, httpx_client=httpx.Client(timeout=DEFAULT_HTTPX_TIMEOUT)
         ),
         git_client=git_client,
         config=resolved_config,
@@ -305,15 +313,23 @@ def _get_issues_client(
         2) Be retrieved from a git platform and not elsewhere (e.g., Jira, Asana, etc.)
         3) Have a specific API key configured
     """
-    issues_client = git_client
+    issues_client: IssuesClient = git_client
     if not resolved_config.issues_url or not resolved_config.issues_source or not resolved_config.issues_regex:
         return issues_client
     if resolved_config.issues_source.is_git_platform:
         if resolved_config.issues_api_key:
             issues_client = get_git_client(
                 source=resolved_config.issues_source, token=resolved_config.issues_api_key, formatter=formatter
             )
+    elif resolved_config.issues_source == IssuesSource.jira:
+        if not resolved_config.issues_api_key or not resolved_config.issues_user:
+            # This is validated earlier in config handler.
+            raise ValueError("To use Jira as issues source, both `issues_user` and `issues_api_key` must be provided.")
+        issues_client = JiraIssuesClient(
+            issues_user=resolved_config.issues_user,
+            issues_api_key=resolved_config.issues_api_key,
+            httpx_client=httpx.Client(timeout=DEFAULT_HTTPX_TIMEOUT),
+        )
     else:
-        # TODO: implement other issues sources
-        raise NotImplementedError("Only GitHub and GitLab are supported as issues sources for now.")
+        raise NotImplementedError("Unsupported issues source")
     return issues_client

src/lgtm_ai/base/constants.py

@@ -0,0 +1,3 @@
+from typing import Final
+
+DEFAULT_HTTPX_TIMEOUT: Final[int] = 3

src/lgtm_ai/base/schemas.py

@@ -14,6 +14,7 @@ class PRSource(StrEnum):
 class IssuesSource(StrEnum):
     github = "github"
     gitlab = "gitlab"
+    jira = "jira"
 
     @property
     def is_git_platform(self) -> bool:

src/lgtm_ai/config/handler.py

@@ -47,6 +47,7 @@ class PartialConfig(BaseModel):
     git_api_key: str | None = None
     ai_api_key: str | None = None
     issues_api_key: str | None = None
+    issues_user: str | None = None
 
 
 class ResolvedConfig(BaseModel):
@@ -107,18 +108,24 @@ class ResolvedConfig(BaseModel):
     issues_api_key: str | None = Field(default=None, repr=False)
     """API key to interact with the issues service (GitHub, GitLab, Jira, etc.)."""
 
+    issues_user: str | None = Field(default=None, repr=False)
+    """Username to interact with the issues service (only needed for Jira)."""
+
     @model_validator(mode="after")
     def validate_issues_options(self) -> Self:
         all_fields = (self.issues_url, self.issues_source)
         if any(field is not None for field in all_fields) and not all(field is not None for field in all_fields):
             raise MissingRequiredConfigError(
                 "If any `--issues-*` configuration is provided, all issues fields must be provided. Check --help."
             )
-        # TODO: Adapt needed credentials and extra options for JIRA (https://github.com/elementsinteractive/lgtm-ai/issues/94)
         if self.issues_source is not None and not self.issues_source.is_git_platform and not self.issues_api_key:
             raise MissingRequiredConfigError(
                 f"An API key is required to access issues from {self.issues_source.value}. Please provide it via the --issues-api-key option or the LGTM_ISSUES_API_KEY environment variable."
             )
+        if self.issues_source == IssuesSource.jira and (not self.issues_user or not self.issues_api_key):
+            raise MissingRequiredConfigError(
+                "A username and an api key are required to access issues from Jira. Please provide them via the --issues-user and --issues-api-key options."
+            )
 
         return self
 
@@ -243,6 +250,7 @@ def _parse_cli_args(self) -> PartialConfig:
             issues_source=self.cli_args.issues_source or None,
             issues_regex=self.cli_args.issues_regex or None,
             issues_api_key=self.cli_args.issues_api_key or None,
+            issues_user=self.cli_args.issues_user or None,
         )
 
     def _parse_env(self) -> PartialConfig:
@@ -252,6 +260,7 @@ def _parse_env(self) -> PartialConfig:
                 git_api_key=os.environ.get("LGTM_GIT_API_KEY", None),
                 ai_api_key=os.environ.get("LGTM_AI_API_KEY", None),
                 issues_api_key=os.environ.get("LGTM_ISSUES_API_KEY", None),
+                issues_user=os.environ.get("LGTM_ISSUES_USER", None),
             )
         except ValidationError as err:
             raise InvalidConfigError(source="Environment variables", errors=err.errors()) from None
@@ -296,6 +305,9 @@ def _resolve_from_multiple_sources(
                 issues_api_key=self.resolver.resolve_string_field(
                     "issues_api_key", from_cli=from_cli, from_env=from_env, required=False, default=None
                 ),
+                issues_user=self.resolver.resolve_string_field(
+                    "issues_user", from_cli=from_cli, from_env=from_env, required=False, default=None
+                ),
             )
         except ValidationError as err:
             raise InvalidOptionsError(err) from None

src/lgtm_ai/jira/__init__.py

@@ -0,0 +1,98 @@
+import logging
+from typing import ClassVar
+
+import httpx
+from lgtm_ai.git_client.schemas import IssueContent
+from pydantic import BaseModel, HttpUrl, ValidationError
+
+logger = logging.getLogger("lgtm")
+
+
+class JiraIssuesClient:
+    API_VERSION: ClassVar[int] = 3
+
+    def __init__(self, issues_user: str, issues_api_key: str, httpx_client: httpx.Client) -> None:
+        self._issues_user = issues_user
+        self._issues_api_key = issues_api_key
+        self._httpx_client = httpx_client
+
+    def get_issue_content(self, issues_url: HttpUrl, issue_id: str) -> IssueContent | None:
+        api_url = f"https://{issues_url.host}/rest/api/{self.API_VERSION}/issue/{issue_id}"
+
+        try:
+            response = self._httpx_client.get(api_url, auth=(self._issues_user, self._issues_api_key))
+            response.raise_for_status()
+            jira_issue = _JiraIssueResponse.model_validate(response.json())
+            return IssueContent(title=jira_issue.title, description=jira_issue.description_text)
+        except httpx.HTTPError:
+            logger.error("Error fetching issue content for %s from Jira at %s", issue_id, issues_url.host)
+            return None
+        except ValidationError as err:
+            logger.error("Error parsing issue content for %s from Jira: %s", issue_id, err)
+            return None
+        except Exception as err:
+            logger.error("Unexpected error fetching issue content for %s from Jira: %s", issue_id, err)
+            return None
+
+
+class _JiraDescriptionContent(BaseModel):
+    """Represents content within a Jira description paragraph."""
+
+    type: str
+    text: str | None = None
+
+
+class _JiraDescriptionParagraph(BaseModel):
+    """Represents a paragraph in Jira description."""
+
+    type: str
+    content: list[_JiraDescriptionContent] | None = None
+
+
+class _JiraDescription(BaseModel):
+    """Represents the Jira description document structure."""
+
+    type: str
+    version: int
+    content: list[_JiraDescriptionParagraph]
+
+    @property
+    def plain_text(self) -> str:
+        """Convert the description to plain text."""
+        text_parts = []
+        for paragraph in self.content:
+            if paragraph.content:
+                paragraph_text = []
+                for content_item in paragraph.content:
+                    if content_item.text:
+                        paragraph_text.append(content_item.text)
+                if paragraph_text:
+                    text_parts.append("".join(paragraph_text))
+        return "\n\n".join(text_parts)
+
+
+class _JiraIssueFields(BaseModel):
+    """Represents the fields section of a Jira issue."""
+
+    summary: str
+    description: _JiraDescription | None = None
+
+
+class _JiraIssueResponse(BaseModel):
+    """Represents a complete Jira issue response."""
+
+    id: str
+    key: str
+    fields: _JiraIssueFields
+
+    @property
+    def title(self) -> str:
+        """Get the issue title (summary)."""
+        return self.fields.summary
+
+    @property
+    def description_text(self) -> str:
+        """Get the description as plain text."""
+        if self.fields.description:
+            return self.fields.description.plain_text
+        return ""

src/lgtm_ai/jira/jira.py

@@ -2,6 +2,7 @@
 
 import httpx
 from lgtm_ai.ai.schemas import GuideResponse, PublishMetadata, ReviewGuide
+from lgtm_ai.base.constants import DEFAULT_HTTPX_TIMEOUT
 from lgtm_ai.base.schemas import PRUrl
 from lgtm_ai.config.handler import ResolvedConfig
 from lgtm_ai.git_client.base import GitClient
@@ -29,7 +30,7 @@ def __init__(
         self.git_client = git_client
         self.config = config
         self.context_retriever = ContextRetriever(
-            git_client=git_client, issues_client=git_client, httpx_client=httpx.Client(timeout=3)
+            git_client=git_client, issues_client=git_client, httpx_client=httpx.Client(timeout=DEFAULT_HTTPX_TIMEOUT)
         )
 
     def generate_review_guide(self, pr_url: PRUrl) -> ReviewGuide:

src/lgtm_ai/review/guide.py

@@ -293,3 +293,19 @@ def test_issues_regex_invalid() -> None:
     )
     with pytest.raises(InvalidOptionsError, match="Invalid regex"):
         handler.resolve_config()
+
+
+@pytest.mark.usefixtures("inject_env_secrets")
+def test_issues_jira_missing_user() -> None:
+    handler = ConfigHandler(
+        cli_args=PartialConfig(
+            issues_url="https://test.atlassian.net/browse/",
+            issues_source="jira",
+            issues_api_key="api-key",
+        ),
+        config_file=None,
+    )
+    with pytest.raises(
+        MissingRequiredConfigError, match="A username and an api key are required to access issues from Jira"
+    ):
+        handler.resolve_config()