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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: release-scope
-Version: 0.2.0
+Version: 0.3.1
 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
@@ -31,19 +31,35 @@ Project-URL: Issues, https://github.com/modern-python/release-scope/issues
 Project-URL: Changelog, https://github.com/modern-python/release-scope/releases
 Description-Content-Type: text/markdown
 
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/release-scope/lockup-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/release-scope/lockup-light.svg">
+    <img alt="release-scope" src="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/release-scope/lockup.png" width="420">
+  </picture>
+</p>
+
 [![PyPI version](https://img.shields.io/pypi/v/release-scope.svg)](https://pypi.org/project/release-scope/)
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/release-scope.svg)](https://pypi.org/project/release-scope/)
+[![Downloads](https://static.pepy.tech/badge/release-scope/month)](https://pepy.tech/projects/release-scope)
 [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/modern-python/release-scope/actions/workflows/ci.yml)
 [![CI](https://github.com/modern-python/release-scope/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/release-scope/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/modern-python/release-scope.svg)](https://github.com/modern-python/release-scope/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/modern-python/release-scope)](https://github.com/modern-python/release-scope/stargazers)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
 
 `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 +76,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 +105,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 +114,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
 {
@@ -104,10 +139,14 @@ uvx release-scope collect --group team/backend --output report.json --cache cach
   uvx release-scope render report.json --output report.md
 ```
 
-The page opens with a table of the services that have pending changes or problems, with the ref each environment runs;
+The page opens with a table of the services that have pending changes or problems, with the ref each environment runs
+and a GitLab compare link from production to the newest pending tag (to the release tag in a `--jira` report);
 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 +155,25 @@ 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.
+
+## Agent skill
+
+[`skills/release-scope`](https://github.com/modern-python/release-scope/tree/main/skills/release-scope) is an agent
+skill that runs `release-scope` through `uvx` and answers release questions from the report. Ask your coding agent
+what in the current repository has not reached production, what a group will ship with the next tag, or whether a
+Jira issue is released and which services it touches. For the current repository the skill takes `--project` from
+the git remote. It keeps the report and cache outside the repository and never writes to GitLab or Jira.
+
+Install it with [skills](https://github.com/vercel-labs/skills):
+
+```sh
+npx skills add modern-python/release-scope
+```
+
+The agent reads the same environment variables as the CLI, so set them first as described under Configuration.
+The skill runs `release-scope>=0.3,<0.4`, the range whose flags and report schema it describes.

release_scope-0.3.1/README.md

@@ -0,0 +1,146 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/release-scope/lockup-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/release-scope/lockup-light.svg">
+    <img alt="release-scope" src="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/release-scope/lockup.png" width="420">
+  </picture>
+</p>
+
+[![PyPI version](https://img.shields.io/pypi/v/release-scope.svg)](https://pypi.org/project/release-scope/)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/release-scope.svg)](https://pypi.org/project/release-scope/)
+[![Downloads](https://static.pepy.tech/badge/release-scope/month)](https://pepy.tech/projects/release-scope)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/modern-python/release-scope/actions/workflows/ci.yml)
+[![CI](https://github.com/modern-python/release-scope/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/release-scope/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/modern-python/release-scope.svg)](https://github.com/modern-python/release-scope/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/modern-python/release-scope)](https://github.com/modern-python/release-scope/stargazers)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+
+`release-scope` collects what sits between production and the default branch across GitLab services: tags, MRs,
+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. 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
+
+```sh
+export RELEASE_SCOPE_GITLAB__ENDPOINT=https://gitlab.example.com
+export RELEASE_SCOPE_GITLAB__TOKEN=glpat-...          # read_api scope
+export RELEASE_SCOPE_ENVIRONMENTS='["prod", "preview"]'
+export RELEASE_SCOPE_PRODUCTION_ENVIRONMENT=prod
+
+uvx release-scope collect --group team/backend --output report.json --cache cache.json
+```
+
+`--group` and `--project` are repeatable and can be mixed. The command exits `1` when any service failed to
+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. 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
+
+Every setting is an environment variable; nothing about a GitLab or Jira instance is built in.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `RELEASE_SCOPE_GITLAB__ENDPOINT` | `https://gitlab.com` | GitLab base URL |
+| `RELEASE_SCOPE_GITLAB__TOKEN` or `GITLAB_TOKEN` | required | Token with `read_api` |
+| `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 |
+
+## Report
+
+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).
+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
+{
+  "kind": "merge_request",
+  "tags": [{"name": "1.2.0", "url": "...", "pipeline": {"id": 201, "status": "success", "failed_jobs": []}}],
+  "merge_requests": [{"iid": 12, "title": "SHOP-12 new endpoint", "url": "..."}],
+  "commits": [{"sha": "c3...", "title": "Merge branch 'feature/SHOP-12'"}],
+  "jira_keys": [{"key": "SHOP-12", "url": "https://jira.example.com/browse/SHOP-12"}],
+  "environments": ["preview"],
+  "main_pipeline": {"id": 103, "status": "failed", "failed_jobs": [{"kind": "job", "name": "lint", "allow_failure": false}]}
+}
+```
+
+## Page
+
+`render` turns a report into a Markdown page for a GitLab wiki, without calling GitLab:
+
+```sh
+uvx release-scope collect --group team/backend --output report.json --cache cache.json; \
+  uvx release-scope render report.json --output report.md
+```
+
+The page opens with a table of the services that have pending changes or problems, with the ref each environment runs
+and a GitLab compare link from production to the newest pending tag (to the release tag in a `--jira` report);
+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 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
+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, 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.
+
+## Agent skill
+
+[`skills/release-scope`](https://github.com/modern-python/release-scope/tree/main/skills/release-scope) is an agent
+skill that runs `release-scope` through `uvx` and answers release questions from the report. Ask your coding agent
+what in the current repository has not reached production, what a group will ship with the next tag, or whether a
+Jira issue is released and which services it touches. For the current repository the skill takes `--project` from
+the git remote. It keeps the report and cache outside the repository and never writes to GitLab or Jira.
+
+Install it with [skills](https://github.com/vercel-labs/skills):
+
+```sh
+npx skills add modern-python/release-scope
+```
+
+The agent reads the same environment variables as the CLI, so set them first as described under Configuration.
+The skill runs `release-scope>=0.3,<0.4`, the range whose flags and report schema it describes.

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

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

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

@@ -17,7 +17,7 @@ classifiers = [
     "Typing :: Typed",
     "Topic :: Software Development :: Build Tools",
 ]
-version = "0.2.0"
+version = "0.3.1"
 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.1}/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.1}/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.1}/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.1}/release_scope/_gitlab.py

@@ -28,6 +28,7 @@ class Project(pydantic.BaseModel):
 
 class Deployable(pydantic.BaseModel):
     web_url: str | None = None
+    tag: bool = False
 
 
 class Deployment(pydantic.BaseModel):
@@ -237,6 +238,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.1/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.1/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"],
+    )