release-scope 0.2.0__tar.gz → 0.3.0__tar.gz

{release_scope-0.2.0 → release_scope-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: release-scope
-Version: 0.2.0
+Version: 0.3.0
 Summary: Collect what sits between production and the default branch across GitLab services: tags, MRs, Jira keys, failed jobs
 Keywords: release,gitlab,jira,deployments,merge-requests,ci,cli,python
 Author: Artur Shiriev
@@ -38,12 +38,15 @@ Description-Content-Type: text/markdown
 [![License](https://img.shields.io/github/license/modern-python/release-scope.svg)](https://github.com/modern-python/release-scope/blob/main/LICENSE)
 
 `release-scope` collects what sits between production and the default branch across GitLab services: tags, MRs,
-Jira keys, failed jobs.
+Jira issues, failed jobs.
 
 For every service it reads the latest successful production deployment, walks the default branch down to that
 commit, and writes one JSON report: a row per merge request or direct commit, newest first, with the tags that
 point into it, the environments running it, the Jira keys its MR mentions, and the failed jobs of its main-branch
-and tag pipelines.
+and tag pipelines. With a Jira token, it also reads the summary and status of every key in one batched search,
+and the GitLab merge requests and commits linked to each issue. GitLab's Jira integration adds those links to the
+issue's Web links whenever a commit or MR mentions it; a link counts only if it starts with
+`RELEASE_SCOPE_GITLAB__ENDPOINT`. The projects they point to are the issue's related services.
 
 ## Quickstart
 
@@ -60,7 +63,23 @@ uvx release-scope collect --group team/backend --output report.json --cache cach
 collect; the report is still written and names the error on that service. A service GitLab denies access to fails
 alone, and its error lists the project settings and member page to check. A project with CI/CD or Environments
 disabled is reported with a warning and no rows, without querying it. Only a rejected token, or a group or project
-passed on the command line that the token cannot see, stops the run.
+passed on the command line that the token cannot see, stops the run. A failed Jira search is recorded in the report
+and also exits `1`; the GitLab part is still written.
+
+## Jira issues
+
+`--jira` scopes the report to Jira issues instead of groups or projects, and needs the Jira settings:
+
+```sh
+uvx release-scope collect --jira SHOP-140 --jira SHOP-141 --output report.json --cache cache.json
+```
+
+It reads the issues and their GitLab links, then collects every project they link to. In each project the rows run
+from the production baseline up to the latest linked change, so they show everything that ships with the issues. The service
+records the release state: `pending` with the nearest tag at or above that change (or none, when a new tag is
+needed), `in_production` when every linked merge request is already deployed, `not_merged` when only open merge
+requests link to it, or `not_found`. Open merge requests and merges into other branches are listed either way.
+`--jira` is repeatable and cannot be combined with `--group` or `--project`; an issue Jira does not return exits `1`.
 
 ## Configuration
 
@@ -73,6 +92,7 @@ Every setting is an environment variable; nothing about a GitLab or Jira instanc
 | `RELEASE_SCOPE_ENVIRONMENTS` | `["production"]` | Environments shown per service, as a JSON list |
 | `RELEASE_SCOPE_PRODUCTION_ENVIRONMENT` | `production` | Environment whose deployed commit starts the range |
 | `RELEASE_SCOPE_JIRA_ENDPOINT` | unset | When set, Jira keys link to `<endpoint>/browse/<KEY>` |
+| `RELEASE_SCOPE_JIRA_TOKEN` or `JIRA_TOKEN` | unset | Jira Server/Data Center personal access token; when set, issues are fetched |
 | `RELEASE_SCOPE_JIRA_PROJECT_KEYS` | `[]` | Keep only keys of these Jira projects; empty keeps all |
 | `RELEASE_SCOPE_MAX_COMMITS` | `1000` | Stop walking a service's range after this many commits |
 | `RELEASE_SCOPE_REQUEST_TIMEOUT` | `10` | Per-request timeout in seconds |
@@ -81,7 +101,9 @@ Every setting is an environment variable; nothing about a GitLab or Jira instanc
 
 The report is versioned by `schema_version`; the models live in
 [`release_scope/_report.py`](https://github.com/modern-python/release-scope/blob/main/release_scope/_report.py).
-One row, trimmed:
+Top-level `jira` is `null` without a Jira token; otherwise it holds `issues` by key (summary, status, status
+category, issue type, linked GitLab changes), the `missing` keys Jira did not return, and an `error` if a Jira
+request failed. One row, trimmed:
 
 ```json
 {
@@ -106,8 +128,11 @@ uvx release-scope collect --group team/backend --output report.json --cache cach
 
 The page opens with a table of the services that have pending changes or problems, with the ref each environment runs;
 services already up to date collapse into one expandable table. Each service with changes then has a collapsible table
-of its rows: the tag linked to its pipeline, the merge requests or direct commit, Jira keys, where the change is
-deployed, and the failed jobs of its main-branch and tag pipelines.
+of its rows: the tag linked to its pipeline, the merge requests or direct commit, Jira keys with summary and status,
+the other services its Jira issues link to, where the change is deployed, and the failed jobs of its main-branch
+and tag pipelines. With Jira issues, the summary table also counts the issues per service whose status is not done.
+A `--jira` report names its issues at the top, shows the tag to release per service, and marks the rows linked to
+the issues.
 
 Chain the two commands with `;`, not `&&`: `collect` exits `1` when a service failed, which is exactly when the page
 should show it. Alert on the exit code of `collect`, not on whether to render. `render` fails only when it cannot
@@ -116,7 +141,8 @@ read the report or write the page.
 ## Cache
 
 `--cache` names a JSON file that is read if present and rewritten atomically after the run. It holds only facts
-that do not change once settled: which merge requests a commit belongs to, and the failed jobs of a finished
-pipeline keyed by its `updated_at`, so a retried job invalidates the entry. Entries the run did not use are
-dropped. A missing, corrupt, or older-schema cache is ignored with a warning; the cache only saves requests and
-never changes the report.
+that do not change once settled: which merge requests a commit belongs to, a merged merge request, and the failed
+jobs of a finished pipeline keyed by its `updated_at`, so a retried job invalidates the entry. Within each project
+the run collected, entries it did not use are dropped; other projects keep theirs, so one cache file serves both
+group and `--jira` runs. A missing, corrupt, or older-schema cache is ignored with a warning; the cache only saves
+requests and never changes the report.

{release_scope-0.2.0 → release_scope-0.3.0}/README.md

@@ -5,12 +5,15 @@
 [![License](https://img.shields.io/github/license/modern-python/release-scope.svg)](https://github.com/modern-python/release-scope/blob/main/LICENSE)
 
 `release-scope` collects what sits between production and the default branch across GitLab services: tags, MRs,
-Jira keys, failed jobs.
+Jira issues, failed jobs.
 
 For every service it reads the latest successful production deployment, walks the default branch down to that
 commit, and writes one JSON report: a row per merge request or direct commit, newest first, with the tags that
 point into it, the environments running it, the Jira keys its MR mentions, and the failed jobs of its main-branch
-and tag pipelines.
+and tag pipelines. With a Jira token, it also reads the summary and status of every key in one batched search,
+and the GitLab merge requests and commits linked to each issue. GitLab's Jira integration adds those links to the
+issue's Web links whenever a commit or MR mentions it; a link counts only if it starts with
+`RELEASE_SCOPE_GITLAB__ENDPOINT`. The projects they point to are the issue's related services.
 
 ## Quickstart
 
@@ -27,7 +30,23 @@ uvx release-scope collect --group team/backend --output report.json --cache cach
 collect; the report is still written and names the error on that service. A service GitLab denies access to fails
 alone, and its error lists the project settings and member page to check. A project with CI/CD or Environments
 disabled is reported with a warning and no rows, without querying it. Only a rejected token, or a group or project
-passed on the command line that the token cannot see, stops the run.
+passed on the command line that the token cannot see, stops the run. A failed Jira search is recorded in the report
+and also exits `1`; the GitLab part is still written.
+
+## Jira issues
+
+`--jira` scopes the report to Jira issues instead of groups or projects, and needs the Jira settings:
+
+```sh
+uvx release-scope collect --jira SHOP-140 --jira SHOP-141 --output report.json --cache cache.json
+```
+
+It reads the issues and their GitLab links, then collects every project they link to. In each project the rows run
+from the production baseline up to the latest linked change, so they show everything that ships with the issues. The service
+records the release state: `pending` with the nearest tag at or above that change (or none, when a new tag is
+needed), `in_production` when every linked merge request is already deployed, `not_merged` when only open merge
+requests link to it, or `not_found`. Open merge requests and merges into other branches are listed either way.
+`--jira` is repeatable and cannot be combined with `--group` or `--project`; an issue Jira does not return exits `1`.
 
 ## Configuration
 
@@ -40,6 +59,7 @@ Every setting is an environment variable; nothing about a GitLab or Jira instanc
 | `RELEASE_SCOPE_ENVIRONMENTS` | `["production"]` | Environments shown per service, as a JSON list |
 | `RELEASE_SCOPE_PRODUCTION_ENVIRONMENT` | `production` | Environment whose deployed commit starts the range |
 | `RELEASE_SCOPE_JIRA_ENDPOINT` | unset | When set, Jira keys link to `<endpoint>/browse/<KEY>` |
+| `RELEASE_SCOPE_JIRA_TOKEN` or `JIRA_TOKEN` | unset | Jira Server/Data Center personal access token; when set, issues are fetched |
 | `RELEASE_SCOPE_JIRA_PROJECT_KEYS` | `[]` | Keep only keys of these Jira projects; empty keeps all |
 | `RELEASE_SCOPE_MAX_COMMITS` | `1000` | Stop walking a service's range after this many commits |
 | `RELEASE_SCOPE_REQUEST_TIMEOUT` | `10` | Per-request timeout in seconds |
@@ -48,7 +68,9 @@ Every setting is an environment variable; nothing about a GitLab or Jira instanc
 
 The report is versioned by `schema_version`; the models live in
 [`release_scope/_report.py`](https://github.com/modern-python/release-scope/blob/main/release_scope/_report.py).
-One row, trimmed:
+Top-level `jira` is `null` without a Jira token; otherwise it holds `issues` by key (summary, status, status
+category, issue type, linked GitLab changes), the `missing` keys Jira did not return, and an `error` if a Jira
+request failed. One row, trimmed:
 
 ```json
 {
@@ -73,8 +95,11 @@ uvx release-scope collect --group team/backend --output report.json --cache cach
 
 The page opens with a table of the services that have pending changes or problems, with the ref each environment runs;
 services already up to date collapse into one expandable table. Each service with changes then has a collapsible table
-of its rows: the tag linked to its pipeline, the merge requests or direct commit, Jira keys, where the change is
-deployed, and the failed jobs of its main-branch and tag pipelines.
+of its rows: the tag linked to its pipeline, the merge requests or direct commit, Jira keys with summary and status,
+the other services its Jira issues link to, where the change is deployed, and the failed jobs of its main-branch
+and tag pipelines. With Jira issues, the summary table also counts the issues per service whose status is not done.
+A `--jira` report names its issues at the top, shows the tag to release per service, and marks the rows linked to
+the issues.
 
 Chain the two commands with `;`, not `&&`: `collect` exits `1` when a service failed, which is exactly when the page
 should show it. Alert on the exit code of `collect`, not on whether to render. `render` fails only when it cannot
@@ -83,7 +108,8 @@ read the report or write the page.
 ## Cache
 
 `--cache` names a JSON file that is read if present and rewritten atomically after the run. It holds only facts
-that do not change once settled: which merge requests a commit belongs to, and the failed jobs of a finished
-pipeline keyed by its `updated_at`, so a retried job invalidates the entry. Entries the run did not use are
-dropped. A missing, corrupt, or older-schema cache is ignored with a warning; the cache only saves requests and
-never changes the report.
+that do not change once settled: which merge requests a commit belongs to, a merged merge request, and the failed
+jobs of a finished pipeline keyed by its `updated_at`, so a retried job invalidates the entry. Within each project
+the run collected, entries it did not use are dropped; other projects keep theirs, so one cache file serves both
+group and `--jira` runs. A missing, corrupt, or older-schema cache is ignored with a warning; the cache only saves
+requests and never changes the report.

{release_scope-0.2.0 → release_scope-0.3.0}/pyproject.toml

@@ -25,7 +25,7 @@ classifiers = [
     "Typing :: Typed",
     "Topic :: Software Development :: Build Tools",
 ]
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
     "typer>=0.13",
     "pydantic>=2; python_version < '3.12'",

{release_scope-0.2.0 → release_scope-0.3.0}/pyproject.toml.orig

@@ -17,7 +17,7 @@ classifiers = [
     "Typing :: Typed",
     "Topic :: Software Development :: Build Tools",
 ]
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
     "typer>=0.13",
     # The first release whose pydantic-core ships a wheel for each interpreter.

{release_scope-0.2.0 → release_scope-0.3.0}/release_scope/__main__.py

@@ -1,17 +1,18 @@
 import importlib.metadata
+import json
 import pathlib
 import typing
 
 import modern_di_typer
-import pydantic
 import typer
 
 from release_scope import ioc
 from release_scope._cache import Cache
 from release_scope._errors import ConfigError, ReleaseScopeError
 from release_scope._files import write_text_atomic
+from release_scope._jira_keys import JIRA_KEY_PATTERN
 from release_scope._render import render_markdown
-from release_scope._report import Report
+from release_scope._report import SCHEMA_VERSION, Report
 from release_scope._settings import Settings, load_settings
 from release_scope._use_case import CollectUseCase
 
@@ -70,19 +71,25 @@ def _collect_command(  # noqa: PLR0913, PLR0917
         pathlib.Path | None,
         typer.Option("--cache", help="Cache JSON; read if present, rewritten in place after the run."),
     ] = None,
+    jira: typing.Annotated[
+        list[str] | None,
+        typer.Option("--jira", "-j", help="Jira issue key; collect only the services it links to. Repeatable."),
+    ] = None,
 ) -> None:
     try:
-        if not group and not project:
-            msg = "Pass at least one --group or --project."
-            raise ConfigError(msg)
+        _check_selection(groups=group or [], projects=project or [], keys=jira or [])
         settings = load_settings({})
         modern_di_typer.fetch_di_container(ctx).set_context(Settings, settings)
         cache, cache_warning = Cache.load(cache_path) if cache_path else (Cache(), None)
         if cache_warning:
             typer.echo(f"Warning: {cache_warning}", err=True)
-        report = _resolve_use_case(ctx=ctx)(
-            groups=group or [], projects=project or [], include_subgroups=include_subgroups, cache=cache
-        )
+        use_case = _resolve_use_case(ctx=ctx)
+        if jira:
+            report = use_case.for_issues(keys=list(dict.fromkeys(jira)), cache=cache)
+        else:
+            report = use_case(
+                groups=group or [], projects=project or [], include_subgroups=include_subgroups, cache=cache
+            )
     except ReleaseScopeError as err:
         typer.echo(f"Error: {err}", err=True)
         raise typer.Exit(code=err.exit_code) from err
@@ -95,18 +102,54 @@ def _collect_command(  # noqa: PLR0913, PLR0917
     typer.echo(f"{len(report.services)} services, {rows} rows, {len(failed)} failed -> {output}", err=True)
     for service in failed:
         typer.echo(f"Error: {service.error}", err=True)
-    if failed:
+    jira_errors: typing.Final = _jira_errors(report)
+    for message in jira_errors:
+        typer.echo(f"Error: {message}", err=True)
+    if failed or jira_errors:
         raise typer.Exit(code=1)
 
 
+def _check_selection(
+    *, groups: typing.Sequence[str], projects: typing.Sequence[str], keys: typing.Sequence[str]
+) -> None:
+    if keys and (groups or projects):
+        msg = "Pass either --jira or --group/--project, not both."
+        raise ConfigError(msg)
+    if not keys and not groups and not projects:
+        msg = "Pass --jira, or at least one --group or --project."
+        raise ConfigError(msg)
+    for key in keys:
+        if not JIRA_KEY_PATTERN.fullmatch(key):
+            msg = f"Not a Jira issue key: {key}."
+            raise ConfigError(msg)
+
+
+def _jira_errors(report: Report) -> list[str]:
+    if report.jira is None:
+        return []
+    errors: typing.Final = [f"Jira has no issue {key}." for key in report.jira_scope if key in report.jira.missing]
+    if report.jira.error:
+        errors.append(report.jira.error)
+    return errors
+
+
 @MAIN_APP.command("render", help="Render a JSON report as a Markdown page for a GitLab wiki.")
 def _render_command(
     report_path: typing.Annotated[pathlib.Path, typer.Argument(help="Report JSON written by `collect`.")],
     output: typing.Annotated[pathlib.Path, typer.Option("--output", "-o", help="Where to write the Markdown page.")],
 ) -> None:
     try:
-        report = Report.model_validate_json(report_path.read_bytes())
-    except (OSError, pydantic.ValidationError) as exc:
+        raw = json.loads(report_path.read_bytes())
+        version = raw.get("schema_version") if isinstance(raw, dict) else None
+        if isinstance(version, int) and version < SCHEMA_VERSION:
+            typer.echo(
+                f"Error: Cannot read report {report_path}: schema_version {version} is not supported; "
+                "run collect again.",
+                err=True,
+            )
+            raise typer.Exit(code=ConfigError.exit_code)
+        report = Report.model_validate(raw)
+    except (OSError, ValueError) as exc:
         typer.echo(f"Error: Cannot read report {report_path}: {type(exc).__name__}.", err=True)
         raise typer.Exit(code=ConfigError.exit_code) from exc
     try:

{release_scope-0.2.0 → release_scope-0.3.0}/release_scope/_cache.py

@@ -11,6 +11,8 @@ from release_scope._report import FailedJob
 
 CACHE_SCHEMA_VERSION: typing.Final = 1
 
+_EntryT = typing.TypeVar("_EntryT")
+
 
 class CachedPipeline(pydantic.BaseModel):
     updated_at: str
@@ -21,12 +23,14 @@ class CacheData(pydantic.BaseModel):
     schema_version: typing.Literal[1] = CACHE_SCHEMA_VERSION
     commit_merge_requests: dict[str, dict[str, list[MergeRequest]]] = pydantic.Field(default_factory=dict)
     pipelines: dict[str, dict[str, CachedPipeline]] = pydantic.Field(default_factory=dict)
+    merge_requests: dict[str, dict[str, MergeRequest]] = pydantic.Field(default_factory=dict)
 
 
 @dataclasses.dataclass(slots=True, kw_only=True)
 class Cache:
     previous: CacheData = dataclasses.field(default_factory=CacheData)
     current: CacheData = dataclasses.field(default_factory=CacheData)
+    visited: set[str] = dataclasses.field(default_factory=set)
 
     @classmethod
     def load(cls, path: pathlib.Path) -> tuple["Cache", str | None]:
@@ -38,7 +42,30 @@ class Cache:
             return cls(), f"Ignoring unreadable cache {path}: {type(exc).__name__}."
 
     def save(self, path: pathlib.Path) -> None:
-        write_text_atomic(path, self.current.model_dump_json(indent=2))
+        write_text_atomic(path, self.pruned().model_dump_json(indent=2))
+
+    def visit(self, project_id: int) -> None:
+        self.visited.add(str(project_id))
+
+    def pruned(self) -> CacheData:
+        return CacheData(
+            commit_merge_requests=self._unvisited(self.previous.commit_merge_requests)
+            | self.current.commit_merge_requests,
+            pipelines=self._unvisited(self.previous.pipelines) | self.current.pipelines,
+            merge_requests=self._unvisited(self.previous.merge_requests) | self.current.merge_requests,
+        )
+
+    def _unvisited(self, entries: dict[str, _EntryT]) -> dict[str, _EntryT]:
+        return {project: entry for project, entry in entries.items() if project not in self.visited}
+
+    def get_merge_request(self, project_id: int, iid: int) -> MergeRequest | None:
+        cached = self.previous.merge_requests.get(str(project_id), {}).get(str(iid))
+        if cached is not None:
+            self.put_merge_request(project_id, cached)
+        return cached
+
+    def put_merge_request(self, project_id: int, merge_request: MergeRequest) -> None:
+        self.current.merge_requests.setdefault(str(project_id), {})[str(merge_request.iid)] = merge_request
 
     def get_commit_merge_requests(self, project_id: int, sha: str) -> list[MergeRequest] | None:
         cached = self.previous.commit_merge_requests.get(str(project_id), {}).get(sha)
@@ -69,3 +96,7 @@ class Cache:
             **self.previous.pipelines.get(key, {}),
             **self.current.pipelines.get(key, {}),
         }
+        self.current.merge_requests[key] = {
+            **self.previous.merge_requests.get(key, {}),
+            **self.current.merge_requests.get(key, {}),
+        }

{release_scope-0.2.0 → release_scope-0.3.0}/release_scope/_errors.py

@@ -21,3 +21,7 @@ class GitLabError(ReleaseScopeError):
         self.resource = resource
         self.status = status
         self.reason = reason
+
+
+class JiraError(ReleaseScopeError):
+    pass

{release_scope-0.2.0 → release_scope-0.3.0}/release_scope/_gitlab.py

@@ -237,6 +237,11 @@ class GitLabApi:
         )
         return merge_requests
 
+    def get_merge_request(self, project_id: int, iid: int) -> MergeRequest:
+        return self._get(
+            f"{_API}/projects/{project_id}/merge_requests/{iid}", {}, MergeRequest, resource="merge_requests"
+        )
+
     def commit_merge_requests(self, project_id: int, sha: str) -> list[MergeRequest]:
         merge_requests, _ = self._pages(
             f"{_API}/projects/{project_id}/repository/commits/{sha}/merge_requests",

release_scope-0.3.0/release_scope/_jira.py

@@ -0,0 +1,118 @@
+import collections.abc
+import dataclasses
+import typing
+
+import httpware
+import pydantic
+
+from release_scope._errors import JiraError
+
+
+_SEARCH: typing.Final = "/rest/api/2/search"
+_ISSUE: typing.Final = "/rest/api/2/issue"
+_BATCH_SIZE: typing.Final = 100
+_FIELDS: typing.Final = ("summary", "status", "issuetype")
+
+
+class StatusCategory(pydantic.BaseModel):
+    key: str | None = None
+
+
+class Status(pydantic.BaseModel):
+    name: str
+    category: StatusCategory | None = pydantic.Field(default=None, alias="statusCategory")
+
+
+class IssueType(pydantic.BaseModel):
+    name: str
+
+
+class IssueFields(pydantic.BaseModel):
+    summary: str
+    status: Status
+    issuetype: IssueType | None = None
+
+
+class Issue(pydantic.BaseModel):
+    key: str
+    fields: IssueFields
+
+
+class _SearchResults(pydantic.BaseModel):
+    total: int
+    issues: list[Issue]
+
+
+class RemoteObject(pydantic.BaseModel):
+    url: str | None = None
+
+
+class RemoteLink(pydantic.BaseModel):
+    target: RemoteObject | None = pydantic.Field(default=None, alias="object")
+
+
+class _RemoteLinks(pydantic.RootModel[list[RemoteLink]]):
+    pass
+
+
+def _error_messages(exc: httpware.StatusError) -> str:
+    try:
+        payload: typing.Final = exc.response.json()
+    except ValueError:
+        return ""
+    messages: typing.Final = payload.get("errorMessages") if isinstance(payload, dict) else None
+    if not isinstance(messages, list):
+        return ""
+    return " ".join(str(message) for message in messages)
+
+
+def _translate(exc: httpware.ClientError, *, target: str) -> JiraError:
+    if isinstance(exc, httpware.UnauthorizedError):
+        return JiraError("Jira rejected the token (401). Check that it is valid and not expired.")
+    if isinstance(exc, httpware.StatusError):
+        status: typing.Final = exc.response.status_code
+        details: typing.Final = _error_messages(exc)
+        suffix: typing.Final = f": {details.rstrip('.')}." if details else "."
+        return JiraError(f"Jira returned {status} for {target}{suffix}")
+    return JiraError(f"Jira request for {target} failed: {type(exc).__name__}.")
+
+
+def _batches(keys: collections.abc.Sequence[str]) -> collections.abc.Iterator[collections.abc.Sequence[str]]:
+    for start in range(0, len(keys), _BATCH_SIZE):
+        yield keys[start : start + _BATCH_SIZE]
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class JiraApi:
+    http: httpware.Client
+
+    def search_issues(self, keys: collections.abc.Sequence[str]) -> list[Issue]:
+        issues: typing.Final[list[Issue]] = []
+        for batch in _batches(keys):
+            quoted = ", ".join(f'"{key}"' for key in batch)
+            issues.extend(self._search(f"key in ({quoted})"))
+        return issues
+
+    def _search(self, jql: str) -> list[Issue]:
+        issues: typing.Final[list[Issue]] = []
+        while True:
+            body = {
+                "jql": jql,
+                "fields": list(_FIELDS),
+                "startAt": len(issues),
+                "maxResults": _BATCH_SIZE,
+                "validateQuery": False,
+            }
+            try:
+                page = self.http.post(_SEARCH, json=body, response_model=_SearchResults)
+            except httpware.ClientError as exc:
+                raise _translate(exc, target="the issue search") from exc
+            issues.extend(page.issues)
+            if not page.issues or len(issues) >= page.total:
+                return issues
+
+    def remote_links(self, key: str) -> list[RemoteLink]:
+        try:
+            return self.http.get(f"{_ISSUE}/{key}/remotelink", response_model=_RemoteLinks).root
+        except httpware.ClientError as exc:
+            raise _translate(exc, target=f"the remote links of {key}") from exc

release_scope-0.3.0/release_scope/_links.py

@@ -0,0 +1,28 @@
+import re
+import typing
+
+from release_scope._report import LinkedChange
+
+
+_CHANGE_PATH: typing.Final = re.compile(
+    r"(?P<project>[^?#]+?)/-/(?:merge_requests/(?P<iid>\d+)|commit/(?P<sha>[0-9a-fA-F]{7,64}))(?:[/?#].*)?"
+)
+
+
+def parse_gitlab_link(url: str | None, gitlab_endpoint: str) -> LinkedChange | None:
+    base: typing.Final = gitlab_endpoint.rstrip("/") + "/"
+    if not url or not url.startswith(base):
+        return None
+    match: typing.Final = _CHANGE_PATH.fullmatch(url.removeprefix(base))
+    if match is None:
+        return None
+    project: typing.Final = match["project"]
+    iid: typing.Final = match["iid"]
+    return LinkedChange(
+        kind="merge_request" if iid else "commit",
+        project=project,
+        project_url=base + project,
+        url=url,
+        iid=int(iid) if iid else None,
+        sha=match["sha"],
+    )

{release_scope-0.2.0 → release_scope-0.3.0}/release_scope/_render.py

@@ -3,7 +3,18 @@ import datetime
 import html
 import typing
 
-from release_scope._report import EnvironmentState, FailedJob, PipelineState, Report, Row, Service, TagRef
+from release_scope._report import (
+    EnvironmentState,
+    FailedJob,
+    JiraIssue,
+    JiraKeyRef,
+    JiraState,
+    PipelineState,
+    Report,
+    Row,
+    Service,
+    TagRef,
+)
 
 
 _STATUS_ICONS: typing.Final = {
@@ -22,8 +33,9 @@ _STATUS_ICONS: typing.Final = {
 _LEGEND: typing.Final = (
     "Legend: ✅ success · ❌ failed · 🔄 running · ⏭ canceled or skipped · ⚠️ warning or allowed failure"
 )
-_ROW_HEADER: typing.Final = ("Tag", "Change", "Jira", "Deployed to", "Failed jobs")
 _FAILED, _SKIPPED, _PENDING = 0, 1, 2
+_UNRELEASED: typing.Final = {"not_merged": "⏳ not merged", "not_found": "⚠️ linked change not found"}
+_LINKED: typing.Final = "🎯"
 
 
 def _inline(value: str) -> str:
@@ -69,6 +81,8 @@ def _state(service: Service) -> int | None:
         return _FAILED
     if service.rows:
         return _PENDING
+    if service.release and service.release.state in _UNRELEASED:
+        return _SKIPPED
     return _SKIPPED if service.warnings else None
 
 
@@ -99,19 +113,30 @@ def _failure_counts(service: Service) -> str:
 
 def _pending(service: Service) -> str:
     state: typing.Final = _state(service)
+    release: typing.Final = service.release
     if state == _FAILED:
         return "❌ failed to collect"
     if state == _SKIPPED:
-        return "⚠️ see below"
-    untagged: typing.Final = "" if service.rows[0].tags else " · untagged head"
-    return f"{_plural(len(service.rows), 'change')}{untagged}"
+        return _UNRELEASED.get(release.state, "⚠️ see below") if release else "⚠️ see below"
+    if release:
+        suffix = f" · release {_tag(release.tag)}" if release.tag else " · needs a new tag"
+    else:
+        suffix = "" if service.rows[0].tags else " · untagged head"
+    return f"{_plural(len(service.rows), 'change')}{suffix}"
+
+
+def _not_done(service: Service, issues: dict[str, JiraIssue]) -> str:
+    keys: typing.Final = {key.key for row in service.rows for key in row.jira_keys}
+    count: typing.Final = sum(1 for key in keys if key in issues and issues[key].status_category != "done")
+    return f"{count} not done" if count else ""
 
 
-def _summary_row(service: Service, environments: list[str]) -> list[str]:
+def _summary_row(service: Service, environments: list[str], jira: JiraState | None) -> list[str]:
     return [
         _link(_cell(service.project), service.project_url),
         *(_environment_ref(_environment(service, name)) for name in environments),
         _pending(service),
+        *([_not_done(service, jira.issues)] if jira else []),
         _failure_counts(service),
     ]
 
@@ -161,11 +186,30 @@ def _failed_jobs(row: Row) -> str:
     return "<br>".join(parts)
 
 
-def _row(row: Row) -> list[str]:
+def _jira_key(key: JiraKeyRef, issues: dict[str, JiraIssue]) -> str:
+    text: typing.Final = _link(_cell(key.key), key.url)
+    issue: typing.Final = issues.get(key.key)
+    return f"{text} {_cell(issue.summary)} · {_cell(issue.status)}" if issue else text
+
+
+def _related_services(row: Row, project: str, issues: dict[str, JiraIssue]) -> str:
+    related: typing.Final = {
+        link.project: link.project_url
+        for key in row.jira_keys
+        if key.key in issues
+        for link in issues[key.key].links
+        if link.project != project
+    }
+    return ", ".join(_link(_cell(name), related[name]) for name in sorted(related))
+
+
+def _row(row: Row, project: str, jira: JiraState | None) -> list[str]:
+    issues: typing.Final = jira.issues if jira else {}
     return [
         "<br>".join(_tag(tag) for tag in row.tags),
-        _merge_requests_or_commits(row),
-        ", ".join(_link(_cell(key.key), key.url) for key in row.jira_keys),
+        f"{_LINKED} {_merge_requests_or_commits(row)}" if row.linked else _merge_requests_or_commits(row),
+        "<br>".join(_jira_key(key, issues) for key in row.jira_keys),
+        *([_related_services(row, project, issues)] if jira else []),
         ", ".join(_cell(name) for name in row.environments),
         _failed_jobs(row),
     ]
@@ -179,7 +223,7 @@ def _counts(service: Service) -> str:
     )
 
 
-def _rows_section(service: Service, production: str) -> list[str]:
+def _rows_section(service: Service, production: str, jira: JiraState | None) -> list[str]:
     ordered: typing.Final = sorted(service.environments, key=lambda item: item.name != production)
     environments: typing.Final = [f"{_cell(item.name)} {_environment_ref(item)}" for item in ordered]
     production_state: typing.Final = _environment(service, production)
@@ -189,35 +233,59 @@ def _rows_section(service: Service, production: str) -> list[str]:
         "",
         *_collapsed(
             f"{_plural(len(service.rows), 'change')}{since}",
-            _table(_ROW_HEADER, (_row(row) for row in service.rows)),
+            _table(
+                ["Tag", "Change", "Jira", *(["Related services"] if jira else []), "Deployed to", "Failed jobs"],
+                (_row(row, service.project, jira) for row in service.rows),
+            ),
         ),
     ]
 
 
-def _service_section(service: Service, production: str) -> list[str]:
+def _service_section(service: Service, production: str, jira: JiraState | None) -> list[str]:
     lines: typing.Final = [f"## {_inline(service.project)}", ""]
     if service.error:
         lines.extend([f"❌ {_inline(service.error)}", ""])
     lines.extend(line for warning in service.warnings for line in (f"⚠️ {_inline(warning)}", ""))
+    release: typing.Final = service.release
+    if release and release.pending_merge_requests:
+        waiting: typing.Final = ", ".join(
+            _reference(f"!{item.iid}", item.url, item.title, f"@{item.author}" if item.author else None)
+            for item in release.pending_merge_requests
+        )
+        lines.extend([f"⏳ Not merged: {waiting}", ""])
+    if release and release.state == "not_found":
+        lines.extend(["⚠️ No linked change was found between production and the head of the default branch.", ""])
     if service.rows:
-        lines.extend(_rows_section(service, production))
+        lines.extend(_rows_section(service, production, jira))
     return lines
 
 
+def _scope_issue(key: str, jira: JiraState | None) -> str:
+    issue: typing.Final = jira.issues.get(key) if jira else None
+    if issue is None:
+        return f"- {_inline(key)} · not found in Jira"
+    return f"- {_link(_inline(key), issue.url)} {_cell(issue.summary)} · {_cell(issue.status)}"
+
+
 def render_markdown(report: Report) -> str:
     production: typing.Final = report.production_environment
     collected: typing.Final = report.collected_at.astimezone(datetime.UTC).strftime("%Y-%m-%d %H:%M")
+    jira: typing.Final = report.jira
+    scope: typing.Final = report.jira_scope
     lines: typing.Final = [
-        "# Release scope",
+        f"# Release scope: {', '.join(_inline(key) for key in scope)}" if scope else "# Release scope",
         "",
         (
             f"Collected {collected} UTC. Changes run from the commit on `{_inline(production)}` "
-            "to the head of the default branch."
+            + ("to the latest change linked to the issues." if scope else "to the head of the default branch.")
         ),
         "",
-        _LEGEND,
-        "",
     ]
+    if scope:
+        lines.extend([*(_scope_issue(key, jira) for key in scope), ""])
+    lines.extend([f"{_LEGEND} · {_LINKED} linked to the issues" if scope else _LEGEND, ""])
+    if jira and jira.error:
+        lines.extend([f"❌ {_inline(jira.error)}", ""])
     if not report.services:
         lines.append("No services were collected.")
         return "\n".join(lines) + "\n"
@@ -229,8 +297,14 @@ def render_markdown(report: Report) -> str:
     up_to_date: typing.Final = [service for service in report.services if _state(service) is None]
     environments: typing.Final = _environment_names(report)
     if attention:
-        header: typing.Final = ["Service", *(_cell(name) for name in environments), "Pending", "Failed jobs"]
-        lines.extend([*_table(header, (_summary_row(service, environments) for service in attention)), ""])
+        header: typing.Final = [
+            "Service",
+            *(_cell(name) for name in environments),
+            "Pending",
+            *(["Jira"] if jira else []),
+            "Failed jobs",
+        ]
+        lines.extend([*_table(header, (_summary_row(service, environments, jira) for service in attention)), ""])
     else:
         lines.extend(["All services are up to date.", ""])
     if up_to_date:
@@ -247,5 +321,5 @@ def render_markdown(report: Report) -> str:
             )
         )
     for service in attention:
-        lines.extend(_service_section(service, production))
+        lines.extend(_service_section(service, production, jira))
     return "\n".join(lines).rstrip("\n") + "\n"

{release_scope-0.2.0 → release_scope-0.3.0}/release_scope/_report.py

@@ -4,7 +4,7 @@ import typing
 import pydantic
 
 
-SCHEMA_VERSION: typing.Final = 1
+SCHEMA_VERSION: typing.Final = 2
 
 
 class FailedJob(pydantic.BaseModel):
@@ -61,6 +61,7 @@ class Row(pydantic.BaseModel):
     jira_keys: list[JiraKeyRef]
     environments: list[str]
     main_pipeline: PipelineState | None
+    linked: bool = False
 
 
 class EnvironmentState(pydantic.BaseModel):
@@ -71,6 +72,12 @@ class EnvironmentState(pydantic.BaseModel):
     deployment_url: str | None
 
 
+class Release(pydantic.BaseModel):
+    state: typing.Literal["pending", "in_production", "not_merged", "not_found"]
+    tag: TagRef | None = None
+    pending_merge_requests: list[MergeRequestRef] = pydantic.Field(default_factory=list)
+
+
 class Service(pydantic.BaseModel):
     project: str
     project_url: str
@@ -79,10 +86,38 @@ class Service(pydantic.BaseModel):
     rows: list[Row] = pydantic.Field(default_factory=list)
     warnings: list[str] = pydantic.Field(default_factory=list)
     error: str | None = None
+    release: Release | None = None
+
+
+class LinkedChange(pydantic.BaseModel):
+    kind: typing.Literal["merge_request", "commit"]
+    project: str
+    project_url: str
+    url: str
+    iid: int | None = None
+    sha: str | None = None
+
+
+class JiraIssue(pydantic.BaseModel):
+    key: str
+    summary: str
+    status: str
+    status_category: str | None
+    issue_type: str | None
+    url: str | None = None
+    links: list[LinkedChange] = pydantic.Field(default_factory=list)
+
+
+class JiraState(pydantic.BaseModel):
+    issues: dict[str, JiraIssue] = pydantic.Field(default_factory=dict)
+    missing: list[str] = pydantic.Field(default_factory=list)
+    error: str | None = None
 
 
 class Report(pydantic.BaseModel):
-    schema_version: typing.Literal[1] = SCHEMA_VERSION
+    schema_version: typing.Literal[2] = SCHEMA_VERSION
     collected_at: datetime.datetime
     production_environment: str
     services: list[Service]
+    jira: JiraState | None = None
+    jira_scope: list[str] = pydantic.Field(default_factory=list)

{release_scope-0.2.0 → release_scope-0.3.0}/release_scope/_settings.py

@@ -27,10 +27,15 @@ class Settings(pydantic_settings.BaseSettings):
         env_nested_delimiter="__",
         case_sensitive=False,
         extra="ignore",
+        populate_by_name=True,
     )
 
     gitlab: GitLabConfig = pydantic.Field(default_factory=GitLabConfig)
     jira_endpoint: str | None = None
+    jira_token: pydantic.SecretStr = pydantic.Field(
+        default=pydantic.SecretStr(""),
+        validation_alias=pydantic.AliasChoices("RELEASE_SCOPE_JIRA_TOKEN", "JIRA_TOKEN"),
+    )
     jira_project_keys: list[str] = pydantic.Field(default_factory=list)
     environments: list[str] = pydantic.Field(default_factory=lambda: ["production"])
     production_environment: str = "production"
@@ -53,4 +58,7 @@ def load_settings(overrides: dict[str, typing.Any]) -> Settings:
     if not settings.gitlab.token.get_secret_value():
         msg = "GitLab token is missing. Set RELEASE_SCOPE_GITLAB__TOKEN or GITLAB_TOKEN."
         raise ConfigError(msg)
+    if settings.jira_token.get_secret_value() and not settings.jira_endpoint:
+        msg = "Jira token is set but RELEASE_SCOPE_JIRA_ENDPOINT is not."
+        raise ConfigError(msg)
     return settings

{release_scope-0.2.0 → release_scope-0.3.0}/release_scope/_use_case.py

@@ -6,17 +6,23 @@ import typing
 from urllib.parse import quote
 
 from release_scope._cache import Cache, CachedPipeline
-from release_scope._errors import AuthError, GitLabError
+from release_scope._errors import AuthError, ConfigError, GitLabError, JiraError
 from release_scope._gitlab import Commit, Deployment, GitLabApi, MergeRequest, Pipeline, Project
+from release_scope._jira import JiraApi
 from release_scope._jira_keys import extract_jira_keys
+from release_scope._links import parse_gitlab_link
 from release_scope._messages import explain_failure, skip_reason
 from release_scope._report import (
     CommitRef,
     EnvironmentState,
     FailedJob,
+    JiraIssue,
     JiraKeyRef,
+    JiraState,
+    LinkedChange,
     MergeRequestRef,
     PipelineState,
+    Release,
     Report,
     Row,
     Service,
@@ -70,9 +76,35 @@ def _commit_ref(commit: Commit) -> CommitRef:
     )
 
 
+def _row_keys(services: list[Service]) -> list[str]:
+    return sorted({key.key for service in services for row in service.rows for key in row.jira_keys})
+
+
+@dataclasses.dataclass(slots=True, kw_only=True)
+class _Walk:
+    truncated: bool
+    drafts: list[RowDraft] = dataclasses.field(default_factory=list)
+    tags_by_sha: dict[str, list[str]] = dataclasses.field(default_factory=dict)
+    main_pipelines: dict[str, Pipeline] = dataclasses.field(default_factory=dict)
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class _LinkTarget:
+    merged: set[int]
+    shas: list[str]
+    pending: list[MergeRequestRef]
+    warnings: list[str]
+
+    def matches(self, draft: RowDraft) -> bool:
+        return any(item.iid in self.merged for item in draft.merge_requests) or any(
+            commit.id.startswith(sha) for commit in draft.commits for sha in self.shas
+        )
+
+
 @dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
 class CollectUseCase:
     api: GitLabApi
+    jira: JiraApi | None
     settings: Settings
 
     def __call__(
@@ -83,25 +115,98 @@ class CollectUseCase:
         include_subgroups: bool,
         cache: Cache,
     ) -> Report:
-        services: typing.Final = []
-        for project in self._resolve_projects(groups=groups, projects=projects, include_subgroups=include_subgroups):
-            try:
-                services.append(self._collect_service(project, cache))
-            except GitLabError as exc:
-                cache.keep_project(project.id)
-                services.append(
-                    Service(
-                        project=project.path_with_namespace,
-                        project_url=project.web_url,
-                        error=explain_failure(project, exc),
-                    )
-                )
+        services: typing.Final = [
+            self._collect_or_explain(project, cache, links=None)
+            for project in self._resolve_projects(groups=groups, projects=projects, include_subgroups=include_subgroups)
+        ]
+        return Report(
+            collected_at=datetime.datetime.now(datetime.UTC),
+            production_environment=self.settings.production_environment,
+            services=services,
+            jira=self._read_issues(self.jira, _row_keys(services)) if self.jira else None,
+        )
+
+    def for_issues(self, *, keys: collections.abc.Sequence[str], cache: Cache) -> Report:
+        if self.jira is None:
+            msg = "--jira needs RELEASE_SCOPE_JIRA_ENDPOINT and RELEASE_SCOPE_JIRA_TOKEN."
+            raise ConfigError(msg)
+        state: typing.Final = self._read_issues(self.jira, keys)
+        services: typing.Final[list[Service]] = []
+        if state.error is None:
+            links_by_project: dict[str, list[LinkedChange]] = {}
+            for key in keys:
+                issue = state.issues.get(key)
+                for link in issue.links if issue else []:
+                    links_by_project.setdefault(link.project, []).append(link)
+            services.extend(
+                self._scoped_service(path, links_by_project[path], cache) for path in sorted(links_by_project)
+            )
+            row_state: typing.Final = self._read_issues(self.jira, sorted(set(_row_keys(services)) - set(keys)))
+            state.issues.update(row_state.issues)
+            state.missing.extend(row_state.missing)
+            state.error = row_state.error
         return Report(
             collected_at=datetime.datetime.now(datetime.UTC),
             production_environment=self.settings.production_environment,
             services=services,
+            jira=state,
+            jira_scope=list(keys),
         )
 
+    def _scoped_service(self, path: str, links: list[LinkedChange], cache: Cache) -> Service:
+        try:
+            project: typing.Final = self.api.get_project(path)
+        except GitLabError as exc:
+            return Service(project=path, project_url=links[0].project_url, error=f"{path}: {exc}")
+        return self._collect_or_explain(project, cache, links=links)
+
+    def _collect_or_explain(self, project: Project, cache: Cache, *, links: list[LinkedChange] | None) -> Service:
+        try:
+            return self._collect_service(project, cache, links=links)
+        except GitLabError as exc:
+            cache.keep_project(project.id)
+            return Service(
+                project=project.path_with_namespace, project_url=project.web_url, error=explain_failure(project, exc)
+            )
+
+    def _read_issues(self, jira: JiraApi, keys: collections.abc.Sequence[str]) -> JiraState:
+        state: typing.Final = JiraState()
+        if not keys:
+            return state
+        try:
+            issues: typing.Final = {issue.key: issue for issue in jira.search_issues(keys)}
+        except JiraError as exc:
+            state.error = str(exc)
+            return state
+        for key in keys:
+            issue = issues.get(key)
+            if issue is None:
+                state.missing.append(key)
+                continue
+            fields = issue.fields
+            state.issues[key] = JiraIssue(
+                key=key,
+                summary=fields.summary,
+                status=fields.status.name,
+                status_category=fields.status.category.key if fields.status.category else None,
+                issue_type=fields.issuetype.name if fields.issuetype else None,
+                url=self._jira_url(key),
+            )
+        try:
+            for key, issue in state.issues.items():
+                issue.links = self._linked_changes(jira, key)
+        except JiraError as exc:
+            state.error = str(exc)
+        return state
+
+    def _linked_changes(self, jira: JiraApi, key: str) -> list[LinkedChange]:
+        changes: typing.Final[dict[str, LinkedChange]] = {}
+        for link in jira.remote_links(key):
+            change = parse_gitlab_link(link.target.url if link.target else None, self.settings.gitlab.endpoint)
+            if change is not None:
+                changes.setdefault(change.url, change)
+        return list(changes.values())
+
     def _resolve_projects(
         self,
         *,
@@ -124,7 +229,8 @@ class CollectUseCase:
             resolved[project.id] = project
         return sorted(resolved.values(), key=lambda item: item.path_with_namespace)
 
-    def _collect_service(self, project: Project, cache: Cache) -> Service:
+    def _collect_service(self, project: Project, cache: Cache, *, links: list[LinkedChange] | None) -> Service:
+        cache.visit(project.id)
         service: typing.Final = Service(
             project=project.path_with_namespace, project_url=project.web_url, default_branch=project.default_branch
         )
@@ -146,39 +252,115 @@ class CollectUseCase:
             service.warnings.append(f"No successful deployment to '{self.settings.production_environment}'.")
             return service
 
+        walk: typing.Final = self._walk(project, project.default_branch, production.sha, service, cache)
+        drafts, linked = walk.drafts, [False] * len(walk.drafts)
+        if links is not None:
+            drafts, linked = self._scope_rows(project, project.default_branch, service, walk, links, cache)
+        service.rows.extend(
+            self._build_row(
+                project=project,
+                draft=draft,
+                tags_by_sha=walk.tags_by_sha,
+                main_pipelines=walk.main_pipelines,
+                environments=service.environments,
+                cache=cache,
+            ).model_copy(update={"linked": is_linked})
+            for draft, is_linked in zip(drafts, linked, strict=True)
+        )
+        return service
+
+    def _walk(self, project: Project, default_branch: str, baseline: str, service: Service, cache: Cache) -> _Walk:
         commits, truncated = self.api.list_first_parent_commits(
-            project.id, f"{production.sha}..{project.default_branch}", max_items=self.settings.max_commits
+            project.id, f"{baseline}..{default_branch}", max_items=self.settings.max_commits
         )
+        walk: typing.Final = _Walk(truncated=truncated)
         if truncated:
             service.warnings.append(f"Stopped after {self.settings.max_commits} commits; older changes are omitted.")
         if not commits:
-            return service
-
+            return walk
         since: typing.Final = min(commit.committed_date for commit in commits)
-        drafts: typing.Final = group_rows(
-            commits, self._commit_merge_requests(project, project.default_branch, commits, since, cache)
-        )
+        walk.drafts = group_rows(commits, self._commit_merge_requests(project, default_branch, commits, since, cache))
         tags, tags_truncated = self.api.list_tags(project.id)
         if tags_truncated:
             service.warnings.append("Tag list was truncated; some tags may be missing from rows.")
-        tags_by_sha: typing.Final[dict[str, list[str]]] = {}
         for tag in tags:
-            tags_by_sha.setdefault(tag.commit.id, []).append(tag.name)
-        main_pipelines: typing.Final = self._latest_by_sha(
-            self.api.list_push_pipelines(project.id, ref=project.default_branch, updated_after=since)
+            walk.tags_by_sha.setdefault(tag.commit.id, []).append(tag.name)
+        walk.main_pipelines = self._latest_by_sha(
+            self.api.list_push_pipelines(project.id, ref=default_branch, updated_after=since)
         )
-        service.rows.extend(
-            self._build_row(
-                project=project,
-                draft=draft,
-                tags_by_sha=tags_by_sha,
-                main_pipelines=main_pipelines,
-                environments=service.environments,
-                cache=cache,
-            )
-            for draft in drafts
+        return walk
+
+    def _scope_rows(  # noqa: PLR0913, PLR0917
+        self,
+        project: Project,
+        default_branch: str,
+        service: Service,
+        walk: _Walk,
+        links: list[LinkedChange],
+        cache: Cache,
+    ) -> tuple[list[RowDraft], list[bool]]:
+        target: typing.Final = self._link_target(project, default_branch, links, cache)
+        service.warnings.extend(target.warnings)
+        index: typing.Final = next(
+            (position for position, draft in enumerate(walk.drafts) if target.matches(draft)), None
+        )
+        service.release = self._release(project, target, walk, index, cache)
+        drafts: typing.Final = walk.drafts[index:] if index is not None else []
+        return drafts, [target.matches(draft) for draft in drafts]
+
+    def _link_target(
+        self, project: Project, default_branch: str, links: list[LinkedChange], cache: Cache
+    ) -> _LinkTarget:
+        merged: typing.Final[set[int]] = set()
+        pending: typing.Final[list[MergeRequestRef]] = []
+        warnings: typing.Final[list[str]] = []
+        for link in links:
+            if link.iid is None:
+                continue
+            merge_request = self._linked_merge_request(project, link.iid, cache)
+            if merge_request.state != "merged":
+                pending.append(_merge_request_ref(merge_request))
+            elif merge_request.target_branch != default_branch:
+                warnings.append(
+                    f"!{merge_request.iid} was merged into {merge_request.target_branch}, not {default_branch}."
+                )
+            else:
+                merged.add(merge_request.iid)
+        return _LinkTarget(
+            merged=merged, shas=[link.sha for link in links if link.sha], pending=pending, warnings=warnings
+        )
+
+    def _linked_merge_request(self, project: Project, iid: int, cache: Cache) -> MergeRequest:
+        cached: typing.Final = cache.get_merge_request(project.id, iid)
+        if cached is not None:
+            return cached
+        merge_request: typing.Final = self.api.get_merge_request(project.id, iid)
+        if merge_request.state == "merged":
+            cache.put_merge_request(project.id, merge_request)
+        return merge_request
+
+    def _release(self, project: Project, target: _LinkTarget, walk: _Walk, index: int | None, cache: Cache) -> Release:
+        if index is None:
+            if target.merged and not walk.truncated:
+                state: typing.Literal["in_production", "not_merged", "not_found"] = "in_production"
+            elif target.pending and not target.merged:
+                state = "not_merged"
+            else:
+                state = "not_found"
+            return Release(state=state, pending_merge_requests=target.pending)
+        tag_name: typing.Final = next(
+            (
+                names[-1]
+                for draft in reversed(walk.drafts[: index + 1])
+                if (names := [name for commit in draft.commits for name in walk.tags_by_sha.get(commit.id, [])])
+            ),
+            None,
+        )
+        return Release(
+            state="pending",
+            tag=self._tag_ref(project, tag_name, cache) if tag_name else None,
+            pending_merge_requests=target.pending,
         )
-        return service
 
     def _commit_merge_requests(
         self, project: Project, default_branch: str, commits: list[Commit], since: datetime.datetime, cache: Cache

{release_scope-0.2.0 → release_scope-0.3.0}/release_scope/ioc.py

@@ -5,12 +5,14 @@ import modern_di
 from modern_di import Scope, providers
 
 from release_scope._gitlab import GitLabApi
+from release_scope._jira import JiraApi
 from release_scope._settings import Settings
 from release_scope._use_case import CollectUseCase
 
 
 _RETRY_STATUS_CODES: typing.Final = frozenset({408, 429, 500, 502, 503, 504})
 _MAX_RESPONSE_BODY_BYTES: typing.Final = 16 * 1024 * 1024
+_JIRA_RETRY_METHODS: typing.Final = frozenset({"GET", "POST"})
 
 
 def _build_gitlab_client(settings: Settings) -> httpware.Client:
@@ -23,8 +25,25 @@ def _build_gitlab_client(settings: Settings) -> httpware.Client:
     )
 
 
-def _close_client(client: httpware.Client) -> None:
-    client.close()
+def _build_jira_client(settings: Settings) -> httpware.Client | None:
+    if not settings.jira_endpoint or not settings.jira_token.get_secret_value():
+        return None
+    return httpware.Client(
+        base_url=settings.jira_endpoint,
+        timeout=settings.request_timeout,
+        headers={"Authorization": f"Bearer {settings.jira_token.get_secret_value()}"},
+        middleware=[httpware.Retry(retry_status_codes=_RETRY_STATUS_CODES, retry_methods=_JIRA_RETRY_METHODS)],
+        max_response_body_bytes=_MAX_RESPONSE_BODY_BYTES,
+    )
+
+
+def _build_jira_api(http: httpware.Client | None) -> JiraApi | None:
+    return JiraApi(http=http) if http else None
+
+
+def _close_client(client: httpware.Client | None) -> None:
+    if client is not None:
+        client.close()
 
 
 class SettingsGroup(modern_di.Group):
@@ -39,10 +58,21 @@ class ClientsGroup(modern_di.Group):
         cache=providers.CacheSettings(finalizer=_close_client),
     )
     gitlab_api = providers.Factory(scope=Scope.APP, creator=GitLabApi, kwargs={"http": gitlab_client})
+    jira_client = providers.Factory(
+        scope=Scope.APP,
+        creator=_build_jira_client,
+        bound_type=None,
+        cache=providers.CacheSettings(finalizer=_close_client),
+    )
+    jira_api = providers.Factory(
+        scope=Scope.APP, creator=_build_jira_api, bound_type=None, kwargs={"http": jira_client}
+    )
 
 
 class UseCasesGroup(modern_di.Group):
-    collect_use_case = providers.Factory(scope=Scope.APP, creator=CollectUseCase)
+    collect_use_case = providers.Factory(
+        scope=Scope.APP, creator=CollectUseCase, kwargs={"jira": ClientsGroup.jira_api}
+    )
 
 
 ALL_GROUPS: typing.Final[list[type[modern_di.Group]]] = [SettingsGroup, ClientsGroup, UseCasesGroup]