release-scope 0.1.0__py3-none-any.whl

release_scope/__main__.py

@@ -0,0 +1,105 @@
+import importlib.metadata
+import pathlib
+import typing
+
+import modern_di_typer
+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._settings import Settings, load_settings
+from release_scope._use_case import CollectUseCase
+
+
+_PACKAGE_NAME: typing.Final = "release-scope"
+
+
+MAIN_APP: typing.Final = typer.Typer(
+    name="release-scope",
+    help="Collect what sits between production and the default branch across GitLab services.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+modern_di_typer.setup_di(MAIN_APP, ioc.container)
+
+
+def _version_callback(value: bool) -> None:
+    if not value:
+        return
+    typer.echo(importlib.metadata.version(_PACKAGE_NAME))
+    raise typer.Exit
+
+
+@MAIN_APP.callback()
+def _main_callback(
+    _version: typing.Annotated[
+        bool | None,
+        typer.Option("--version", callback=_version_callback, is_eager=True, help="Show version and exit."),
+    ] = None,
+) -> None:
+    pass
+
+
+@modern_di_typer.inject
+def _resolve_use_case(
+    use_case: typing.Annotated[CollectUseCase, modern_di_typer.FromDI(CollectUseCase)],
+) -> CollectUseCase:
+    return use_case
+
+
+@MAIN_APP.command("collect", help="Collect pending changes per service into a JSON report.")
+def _collect_command(  # noqa: PLR0913, PLR0917
+    ctx: typer.Context,
+    output: typing.Annotated[pathlib.Path, typer.Option("--output", "-o", help="Where to write the report JSON.")],
+    group: typing.Annotated[
+        list[str] | None, typer.Option("--group", "-g", help="GitLab group path; repeatable.")
+    ] = None,
+    project: typing.Annotated[
+        list[str] | None, typer.Option("--project", "-p", help="GitLab project path; repeatable.")
+    ] = None,
+    include_subgroups: typing.Annotated[
+        bool, typer.Option("--include-subgroups", help="Also collect projects in subgroups of each --group.")
+    ] = False,
+    cache_path: typing.Annotated[
+        pathlib.Path | None,
+        typer.Option("--cache", help="Cache JSON; read if present, rewritten in place after the run."),
+    ] = None,
+) -> None:
+    try:
+        if not group and not project:
+            msg = "Pass at least one --group or --project."
+            raise ConfigError(msg)
+        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
+        )
+    except ReleaseScopeError as err:
+        typer.echo(f"Error: {err}", err=True)
+        raise typer.Exit(code=err.exit_code) from err
+
+    write_text_atomic(output, report.model_dump_json(indent=2))
+    if cache_path:
+        cache.save(cache_path)
+    failed: typing.Final = [service for service in report.services if service.error]
+    rows: typing.Final = sum(len(service.rows) for service in report.services)
+    typer.echo(f"{len(report.services)} services, {rows} rows, {len(failed)} failed -> {output}", err=True)
+    for service in failed:
+        typer.echo(f"Error: {service.project}: {service.error}", err=True)
+    if failed:
+        raise typer.Exit(code=1)
+
+
+def main() -> None:
+    with ioc.container:
+        MAIN_APP()
+
+
+if __name__ == "__main__":
+    main()

release_scope/_cache.py

@@ -0,0 +1,71 @@
+import dataclasses
+import pathlib
+import typing
+
+import pydantic
+
+from release_scope._files import write_text_atomic
+from release_scope._gitlab import MergeRequest
+from release_scope._report import FailedJob
+
+
+CACHE_SCHEMA_VERSION: typing.Final = 1
+
+
+class CachedPipeline(pydantic.BaseModel):
+    updated_at: str
+    failed_jobs: list[FailedJob]
+
+
+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)
+
+
+@dataclasses.dataclass(slots=True, kw_only=True)
+class Cache:
+    previous: CacheData = dataclasses.field(default_factory=CacheData)
+    current: CacheData = dataclasses.field(default_factory=CacheData)
+
+    @classmethod
+    def load(cls, path: pathlib.Path) -> tuple["Cache", str | None]:
+        if not path.exists():
+            return cls(), None
+        try:
+            return cls(previous=CacheData.model_validate_json(path.read_bytes())), None
+        except (OSError, pydantic.ValidationError) as exc:
+            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))
+
+    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)
+        if cached is not None:
+            self.put_commit_merge_requests(project_id, sha, cached)
+        return cached
+
+    def put_commit_merge_requests(self, project_id: int, sha: str, merge_requests: list[MergeRequest]) -> None:
+        self.current.commit_merge_requests.setdefault(str(project_id), {})[sha] = merge_requests
+
+    def get_failed_jobs(self, project_id: int, pipeline_id: int, updated_at: str) -> list[FailedJob] | None:
+        cached = self.previous.pipelines.get(str(project_id), {}).get(str(pipeline_id))
+        if cached is None or cached.updated_at != updated_at:
+            return None
+        self.put_failed_jobs(project_id, pipeline_id, cached)
+        return cached.failed_jobs
+
+    def put_failed_jobs(self, project_id: int, pipeline_id: int, entry: CachedPipeline) -> None:
+        self.current.pipelines.setdefault(str(project_id), {})[str(pipeline_id)] = entry
+
+    def keep_project(self, project_id: int) -> None:
+        key: typing.Final = str(project_id)
+        self.current.commit_merge_requests[key] = {
+            **self.previous.commit_merge_requests.get(key, {}),
+            **self.current.commit_merge_requests.get(key, {}),
+        }
+        self.current.pipelines[key] = {
+            **self.previous.pipelines.get(key, {}),
+            **self.current.pipelines.get(key, {}),
+        }

release_scope/_errors.py

@@ -0,0 +1,17 @@
+import typing
+
+
+class ReleaseScopeError(Exception):
+    exit_code: typing.ClassVar[int] = 1
+
+
+class ConfigError(ReleaseScopeError):
+    exit_code: typing.ClassVar[int] = 2
+
+
+class AuthError(ReleaseScopeError):
+    exit_code: typing.ClassVar[int] = 3
+
+
+class GitLabError(ReleaseScopeError):
+    exit_code: typing.ClassVar[int] = 4

release_scope/_files.py

@@ -0,0 +1,14 @@
+import os
+import pathlib
+import tempfile
+
+
+def write_text_atomic(path: pathlib.Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(
+        "w", encoding="utf-8", dir=path.parent, prefix=f".{path.name}.", suffix=".tmp", delete=False
+    ) as handle:
+        handle.write(text)
+        handle.flush()
+        os.fsync(handle.fileno())
+    pathlib.Path(handle.name).replace(path)

release_scope/_gitlab.py

@@ -0,0 +1,261 @@
+import dataclasses
+import datetime
+import math
+import typing
+from urllib.parse import quote
+
+import httpware
+import pydantic
+
+from release_scope._errors import AuthError, GitLabError
+
+
+_API: typing.Final = "/api/v4"
+_PER_PAGE: typing.Final = 100
+_MAX_PAGES: typing.Final = 50
+
+_ModelT = typing.TypeVar("_ModelT", bound=pydantic.BaseModel)
+
+
+class Project(pydantic.BaseModel):
+    id: int
+    path_with_namespace: str
+    web_url: str
+    default_branch: str | None = None
+
+
+class Deployable(pydantic.BaseModel):
+    web_url: str | None = None
+
+
+class Deployment(pydantic.BaseModel):
+    id: int
+    ref: str
+    sha: str
+    created_at: str
+    deployable: Deployable | None = None
+
+
+class TagCommit(pydantic.BaseModel):
+    id: str
+
+
+class Tag(pydantic.BaseModel):
+    name: str
+    commit: TagCommit
+
+
+class Commit(pydantic.BaseModel):
+    id: str
+    short_id: str
+    title: str
+    message: str = ""
+    author_name: str | None = None
+    committed_date: datetime.datetime
+    web_url: str | None = None
+
+
+class Author(pydantic.BaseModel):
+    username: str | None = None
+    name: str | None = None
+
+
+class MergeRequest(pydantic.BaseModel):
+    iid: int
+    title: str
+    description: str | None = None
+    source_branch: str | None = None
+    target_branch: str
+    state: str
+    web_url: str
+    sha: str | None = None
+    merge_commit_sha: str | None = None
+    squash_commit_sha: str | None = None
+    merged_at: str | None = None
+    author: Author | None = None
+
+
+class Pipeline(pydantic.BaseModel):
+    id: int
+    sha: str
+    ref: str
+    status: str
+    web_url: str
+    updated_at: str
+
+
+class Job(pydantic.BaseModel):
+    name: str
+    stage: str | None = None
+    status: str
+    allow_failure: bool = False
+    web_url: str | None = None
+    failure_reason: str | None = None
+
+
+class DownstreamPipeline(pydantic.BaseModel):
+    web_url: str | None = None
+
+
+class Bridge(Job):
+    downstream_pipeline: DownstreamPipeline | None = None
+
+
+class _Projects(pydantic.RootModel[list[Project]]):
+    pass
+
+
+class _Deployments(pydantic.RootModel[list[Deployment]]):
+    pass
+
+
+class _Tags(pydantic.RootModel[list[Tag]]):
+    pass
+
+
+class _Commits(pydantic.RootModel[list[Commit]]):
+    pass
+
+
+class _MergeRequests(pydantic.RootModel[list[MergeRequest]]):
+    pass
+
+
+class _Pipelines(pydantic.RootModel[list[Pipeline]]):
+    pass
+
+
+class _Jobs(pydantic.RootModel[list[Job]]):
+    pass
+
+
+class _Bridges(pydantic.RootModel[list[Bridge]]):
+    pass
+
+
+def _translate(exc: httpware.ClientError, *, url: str) -> Exception:
+    if isinstance(exc, (httpware.UnauthorizedError, httpware.ForbiddenError)):
+        return AuthError(
+            f"GitLab rejected the token ({exc.response.status_code}) for {url}. It needs 'read_api' scope."
+        )
+    if isinstance(exc, httpware.StatusError):
+        return GitLabError(f"GitLab returned {exc.response.status_code} for {url}.")
+    return GitLabError(f"GitLab request {url} failed: {type(exc).__name__}.")
+
+
+def _quote(value: str) -> str:
+    return quote(value, safe="")
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class GitLabApi:
+    http: httpware.Client
+
+    def _get(self, url: str, params: dict[str, typing.Any], model: type[_ModelT]) -> _ModelT:
+        try:
+            return self.http.get(url, params=params, response_model=model)
+        except httpware.ClientError as exc:
+            raise _translate(exc, url=url) from exc
+
+    def _pages(
+        self,
+        url: str,
+        params: dict[str, typing.Any],
+        model: type[pydantic.RootModel[list[_ModelT]]],
+        *,
+        max_items: int | None = None,
+    ) -> tuple[list[_ModelT], bool]:
+        max_pages: typing.Final = _MAX_PAGES if max_items is None else math.ceil(max_items / _PER_PAGE)
+        items: list[_ModelT] = []
+        for page in range(1, max_pages + 1):
+            try:
+                response, batch = self.http.get_with_response(
+                    url, params={**params, "per_page": _PER_PAGE, "page": page}, response_model=model
+                )
+            except httpware.ClientError as exc:
+                raise _translate(exc, url=url) from exc
+            items.extend(batch.root)
+            if not response.headers.get("x-next-page"):
+                break
+        else:
+            return items[:max_items], True
+        if max_items is not None and len(items) > max_items:
+            return items[:max_items], True
+        return items, False
+
+    def get_project(self, path: str) -> Project:
+        return self._get(f"{_API}/projects/{_quote(path)}", {}, Project)
+
+    def list_group_projects(self, group: str, *, include_subgroups: bool) -> list[Project]:
+        projects, _ = self._pages(
+            f"{_API}/groups/{_quote(group)}/projects",
+            {"archived": "false", "with_shared": "false", "include_subgroups": str(include_subgroups).lower()},
+            _Projects,
+        )
+        return projects
+
+    def latest_deployment(self, project_id: int, environment: str) -> Deployment | None:
+        deployments = self._get(
+            f"{_API}/projects/{project_id}/deployments",
+            {"environment": environment, "status": "success", "order_by": "id", "sort": "desc", "per_page": 1},
+            _Deployments,
+        )
+        return deployments.root[0] if deployments.root else None
+
+    def list_tags(self, project_id: int) -> tuple[list[Tag], bool]:
+        return self._pages(f"{_API}/projects/{project_id}/repository/tags", {}, _Tags)
+
+    def list_first_parent_commits(
+        self, project_id: int, ref_range: str, *, max_items: int
+    ) -> tuple[list[Commit], bool]:
+        return self._pages(
+            f"{_API}/projects/{project_id}/repository/commits",
+            {"ref_name": ref_range, "first_parent": "true"},
+            _Commits,
+            max_items=max_items,
+        )
+
+    def list_merged_merge_requests(
+        self, project_id: int, *, target_branch: str, updated_after: datetime.datetime
+    ) -> list[MergeRequest]:
+        merge_requests, _ = self._pages(
+            f"{_API}/projects/{project_id}/merge_requests",
+            {"state": "merged", "target_branch": target_branch, "updated_after": updated_after.isoformat()},
+            _MergeRequests,
+        )
+        return 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", {}, _MergeRequests
+        )
+        return merge_requests
+
+    def list_push_pipelines(self, project_id: int, *, ref: str, updated_after: datetime.datetime) -> list[Pipeline]:
+        pipelines, _ = self._pages(
+            f"{_API}/projects/{project_id}/pipelines",
+            {"ref": ref, "source": "push", "updated_after": updated_after.isoformat()},
+            _Pipelines,
+        )
+        return pipelines
+
+    def latest_pipeline(self, project_id: int, *, ref: str) -> Pipeline | None:
+        pipelines = self._get(
+            f"{_API}/projects/{project_id}/pipelines",
+            {"ref": ref, "order_by": "id", "sort": "desc", "per_page": 1},
+            _Pipelines,
+        )
+        return pipelines.root[0] if pipelines.root else None
+
+    def failed_jobs(self, project_id: int, pipeline_id: int) -> list[Job]:
+        jobs, _ = self._pages(
+            f"{_API}/projects/{project_id}/pipelines/{pipeline_id}/jobs", {"scope[]": "failed"}, _Jobs
+        )
+        return jobs
+
+    def failed_bridges(self, project_id: int, pipeline_id: int) -> list[Bridge]:
+        # `trigger_jobs` replaces this route only from GitLab 19.2; older instances have `bridges` alone.
+        bridges, _ = self._pages(
+            f"{_API}/projects/{project_id}/pipelines/{pipeline_id}/bridges", {"scope[]": "failed"}, _Bridges
+        )
+        return bridges

release_scope/_jira_keys.py

@@ -0,0 +1,22 @@
+import collections.abc
+import re
+import typing
+
+
+JIRA_KEY_PATTERN: typing.Final = re.compile(r"(?<![A-Za-z0-9])[A-Z][A-Z0-9]+-\d+(?![A-Z0-9])")
+
+
+def extract_jira_keys(
+    texts: collections.abc.Iterable[str | None],
+    *,
+    allowed_projects: collections.abc.Collection[str] = (),
+) -> list[str]:
+    keys: dict[str, None] = {}
+    for text in texts:
+        if not text:
+            continue
+        for key in JIRA_KEY_PATTERN.findall(text):
+            if allowed_projects and key.split("-", 1)[0] not in allowed_projects:
+                continue
+            keys[key] = None
+    return list(keys)

release_scope/_report.py

@@ -0,0 +1,88 @@
+import datetime
+import typing
+
+import pydantic
+
+
+SCHEMA_VERSION: typing.Final = 1
+
+
+class FailedJob(pydantic.BaseModel):
+    kind: typing.Literal["job", "bridge"]
+    name: str
+    stage: str | None
+    status: str
+    allow_failure: bool
+    url: str | None
+    failure_reason: str | None
+    downstream_pipeline_url: str | None = None
+
+
+class PipelineState(pydantic.BaseModel):
+    id: int
+    status: str
+    url: str
+    failed_jobs: list[FailedJob]
+
+
+class TagRef(pydantic.BaseModel):
+    name: str
+    url: str
+    pipeline: PipelineState | None
+
+
+class MergeRequestRef(pydantic.BaseModel):
+    iid: int
+    title: str
+    url: str
+    author: str | None
+    merged_at: str | None
+
+
+class CommitRef(pydantic.BaseModel):
+    sha: str
+    short_sha: str
+    title: str
+    url: str | None
+    author: str | None
+    committed_at: datetime.datetime
+
+
+class JiraKeyRef(pydantic.BaseModel):
+    key: str
+    url: str | None
+
+
+class Row(pydantic.BaseModel):
+    kind: typing.Literal["merge_request", "commit"]
+    tags: list[TagRef]
+    merge_requests: list[MergeRequestRef]
+    commits: list[CommitRef]
+    jira_keys: list[JiraKeyRef]
+    environments: list[str]
+    main_pipeline: PipelineState | None
+
+
+class EnvironmentState(pydantic.BaseModel):
+    name: str
+    ref: str
+    sha: str
+    deployed_at: str
+    deployment_url: str | None
+
+
+class Service(pydantic.BaseModel):
+    project: str
+    project_url: str
+    default_branch: str | None = None
+    environments: list[EnvironmentState] = pydantic.Field(default_factory=list)
+    rows: list[Row] = pydantic.Field(default_factory=list)
+    warnings: list[str] = pydantic.Field(default_factory=list)
+    error: str | None = None
+
+
+class Report(pydantic.BaseModel):
+    schema_version: typing.Literal[1] = SCHEMA_VERSION
+    collected_at: datetime.datetime
+    production_environment: str
+    services: list[Service]

release_scope/_rows.py

@@ -0,0 +1,37 @@
+import collections.abc
+import dataclasses
+
+from release_scope._gitlab import Commit, MergeRequest
+
+
+@dataclasses.dataclass(slots=True, kw_only=True)
+class RowDraft:
+    commits: list[Commit]
+    merge_requests: list[MergeRequest]
+
+
+def match_merge_requests(
+    commits: collections.abc.Sequence[Commit],
+    merge_requests: collections.abc.Iterable[MergeRequest],
+) -> dict[str, list[MergeRequest]]:
+    by_sha: dict[str, dict[int, MergeRequest]] = {}
+    for merge_request in merge_requests:
+        for sha in (merge_request.merge_commit_sha, merge_request.squash_commit_sha, merge_request.sha):
+            if sha:
+                by_sha.setdefault(sha, {})[merge_request.iid] = merge_request
+    return {commit.id: list(by_sha[commit.id].values()) for commit in commits if commit.id in by_sha}
+
+
+def group_rows(
+    commits: collections.abc.Sequence[Commit],
+    commit_merge_requests: collections.abc.Mapping[str, collections.abc.Sequence[MergeRequest]],
+) -> list[RowDraft]:
+    rows: dict[tuple[object, ...], RowDraft] = {}
+    for commit in commits:
+        merge_requests = sorted(commit_merge_requests.get(commit.id, ()), key=lambda item: item.iid)
+        key: tuple[object, ...] = (
+            tuple(item.iid for item in merge_requests) if merge_requests else ("commit", commit.id)
+        )
+        row = rows.setdefault(key, RowDraft(commits=[], merge_requests=list(merge_requests)))
+        row.commits.append(commit)
+    return list(rows.values())

release_scope/_settings.py

@@ -0,0 +1,56 @@
+import typing
+
+import pydantic
+import pydantic_settings
+
+from release_scope._errors import ConfigError
+
+
+class GitLabConfig(pydantic_settings.BaseSettings):
+    model_config = pydantic_settings.SettingsConfigDict(
+        env_prefix="RELEASE_SCOPE_GITLAB__",
+        case_sensitive=False,
+        extra="ignore",
+        populate_by_name=True,
+    )
+
+    endpoint: str = "https://gitlab.com"
+    token: pydantic.SecretStr = pydantic.Field(
+        default=pydantic.SecretStr(""),
+        validation_alias=pydantic.AliasChoices("RELEASE_SCOPE_GITLAB__TOKEN", "GITLAB_TOKEN"),
+    )
+
+
+class Settings(pydantic_settings.BaseSettings):
+    model_config = pydantic_settings.SettingsConfigDict(
+        env_prefix="RELEASE_SCOPE_",
+        env_nested_delimiter="__",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    gitlab: GitLabConfig = pydantic.Field(default_factory=GitLabConfig)
+    jira_endpoint: str | None = None
+    jira_project_keys: list[str] = pydantic.Field(default_factory=list)
+    environments: list[str] = pydantic.Field(default_factory=lambda: ["production"])
+    production_environment: str = "production"
+    request_timeout: float = 10.0
+    max_commits: int = 1000
+
+    @pydantic.model_validator(mode="after")
+    def _production_is_listed(self) -> typing.Self:
+        if self.production_environment not in self.environments:
+            self.environments = [self.production_environment, *self.environments]
+        return self
+
+
+def load_settings(overrides: dict[str, typing.Any]) -> Settings:
+    try:
+        settings: typing.Final = Settings(**overrides)
+    except pydantic.ValidationError as exc:
+        msg = f"Invalid configuration: {exc}"
+        raise ConfigError(msg) from exc
+    if not settings.gitlab.token.get_secret_value():
+        msg = "GitLab token is missing. Set RELEASE_SCOPE_GITLAB__TOKEN or GITLAB_TOKEN."
+        raise ConfigError(msg)
+    return settings

release_scope/_use_case.py

@@ -0,0 +1,272 @@
+import collections.abc
+import dataclasses
+import datetime
+import typing
+from urllib.parse import quote
+
+from release_scope._cache import Cache, CachedPipeline
+from release_scope._errors import GitLabError
+from release_scope._gitlab import Commit, Deployment, GitLabApi, MergeRequest, Pipeline, Project
+from release_scope._jira_keys import extract_jira_keys
+from release_scope._report import (
+    CommitRef,
+    EnvironmentState,
+    FailedJob,
+    JiraKeyRef,
+    MergeRequestRef,
+    PipelineState,
+    Report,
+    Row,
+    Service,
+    TagRef,
+)
+from release_scope._rows import RowDraft, group_rows, match_merge_requests
+from release_scope._settings import Settings
+
+
+_SETTLED_PIPELINE_STATUSES: typing.Final = frozenset({"success", "failed", "canceled", "skipped"})
+
+
+def _environment_state(name: str, deployment: Deployment) -> EnvironmentState:
+    return EnvironmentState(
+        name=name,
+        ref=deployment.ref,
+        sha=deployment.sha,
+        deployed_at=deployment.created_at,
+        deployment_url=deployment.deployable.web_url if deployment.deployable else None,
+    )
+
+
+def _merge_request_ref(merge_request: MergeRequest) -> MergeRequestRef:
+    author: typing.Final = merge_request.author
+    return MergeRequestRef(
+        iid=merge_request.iid,
+        title=merge_request.title,
+        url=merge_request.web_url,
+        author=(author.username or author.name) if author else None,
+        merged_at=merge_request.merged_at,
+    )
+
+
+def _commit_ref(commit: Commit) -> CommitRef:
+    return CommitRef(
+        sha=commit.id,
+        short_sha=commit.short_id,
+        title=commit.title,
+        url=commit.web_url,
+        author=commit.author_name,
+        committed_at=commit.committed_date,
+    )
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class CollectUseCase:
+    api: GitLabApi
+    settings: Settings
+
+    def __call__(
+        self,
+        *,
+        groups: collections.abc.Sequence[str],
+        projects: collections.abc.Sequence[str],
+        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=str(exc))
+                )
+        return Report(
+            collected_at=datetime.datetime.now(datetime.UTC),
+            production_environment=self.settings.production_environment,
+            services=services,
+        )
+
+    def _resolve_projects(
+        self,
+        *,
+        groups: collections.abc.Sequence[str],
+        projects: collections.abc.Sequence[str],
+        include_subgroups: bool,
+    ) -> list[Project]:
+        resolved: dict[int, Project] = {}
+        for group in groups:
+            for project in self.api.list_group_projects(group, include_subgroups=include_subgroups):
+                resolved[project.id] = project
+        for path in projects:
+            project = self.api.get_project(path)
+            resolved[project.id] = project
+        return sorted(resolved.values(), key=lambda item: item.path_with_namespace)
+
+    def _collect_service(self, project: Project, cache: Cache) -> Service:
+        service: typing.Final = Service(
+            project=project.path_with_namespace, project_url=project.web_url, default_branch=project.default_branch
+        )
+        for name in self.settings.environments:
+            deployment = self.api.latest_deployment(project.id, name)
+            if deployment is not None:
+                service.environments.append(_environment_state(name, deployment))
+        production: typing.Final = next(
+            (item for item in service.environments if item.name == self.settings.production_environment), None
+        )
+        if project.default_branch is None:
+            service.warnings.append("Project has no default branch.")
+            return service
+        if production is None:
+            service.warnings.append(f"No successful deployment to '{self.settings.production_environment}'.")
+            return service
+
+        commits, truncated = self.api.list_first_parent_commits(
+            project.id, f"{production.sha}..{project.default_branch}", max_items=self.settings.max_commits
+        )
+        if truncated:
+            service.warnings.append(f"Stopped after {self.settings.max_commits} commits; older changes are omitted.")
+        if not commits:
+            return service
+
+        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)
+        )
+        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)
+        )
+        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 service
+
+    def _commit_merge_requests(
+        self, project: Project, default_branch: str, commits: list[Commit], since: datetime.datetime, cache: Cache
+    ) -> dict[str, list[MergeRequest]]:
+        merged: typing.Final = self.api.list_merged_merge_requests(
+            project.id, target_branch=default_branch, updated_after=since
+        )
+        matched: typing.Final = match_merge_requests(commits, merged)
+        for commit in commits:
+            if commit.id in matched:
+                continue
+            cached = cache.get_commit_merge_requests(project.id, commit.id)
+            if cached is None:
+                cached = [
+                    item
+                    for item in self.api.commit_merge_requests(project.id, commit.id)
+                    if item.state == "merged" and item.target_branch == default_branch
+                ]
+                cache.put_commit_merge_requests(project.id, commit.id, cached)
+            if cached:
+                matched[commit.id] = cached
+        return matched
+
+    @staticmethod
+    def _latest_by_sha(pipelines: list[Pipeline]) -> dict[str, Pipeline]:
+        latest: dict[str, Pipeline] = {}
+        for pipeline in pipelines:
+            if pipeline.sha not in latest or pipeline.id > latest[pipeline.sha].id:
+                latest[pipeline.sha] = pipeline
+        return latest
+
+    def _build_row(  # noqa: PLR0913
+        self,
+        *,
+        project: Project,
+        draft: RowDraft,
+        tags_by_sha: dict[str, list[str]],
+        main_pipelines: dict[str, Pipeline],
+        environments: list[EnvironmentState],
+        cache: Cache,
+    ) -> Row:
+        shas: typing.Final = {commit.id for commit in draft.commits}
+        if draft.merge_requests:
+            texts: list[str | None] = []
+            for merge_request in draft.merge_requests:
+                texts.extend((merge_request.title, merge_request.source_branch, merge_request.description))
+        else:
+            texts = [commit.message or commit.title for commit in draft.commits]
+        head_pipeline: typing.Final = main_pipelines.get(draft.commits[0].id)
+        return Row(
+            kind="merge_request" if draft.merge_requests else "commit",
+            tags=[
+                self._tag_ref(project, name, cache)
+                for commit in draft.commits
+                for name in tags_by_sha.get(commit.id, [])
+            ],
+            merge_requests=[_merge_request_ref(item) for item in draft.merge_requests],
+            commits=[_commit_ref(commit) for commit in draft.commits],
+            jira_keys=[
+                JiraKeyRef(key=key, url=self._jira_url(key))
+                for key in extract_jira_keys(texts, allowed_projects=self.settings.jira_project_keys)
+            ],
+            environments=[item.name for item in environments if item.sha in shas],
+            main_pipeline=self._pipeline_state(project, head_pipeline, cache) if head_pipeline else None,
+        )
+
+    def _tag_ref(self, project: Project, name: str, cache: Cache) -> TagRef:
+        pipeline: typing.Final = self.api.latest_pipeline(project.id, ref=name)
+        return TagRef(
+            name=name,
+            url=f"{project.web_url}/-/tags/{quote(name, safe='')}",
+            pipeline=self._pipeline_state(project, pipeline, cache) if pipeline else None,
+        )
+
+    def _jira_url(self, key: str) -> str | None:
+        if not self.settings.jira_endpoint:
+            return None
+        return f"{self.settings.jira_endpoint.rstrip('/')}/browse/{key}"
+
+    def _pipeline_state(self, project: Project, pipeline: Pipeline, cache: Cache) -> PipelineState:
+        failed_jobs = cache.get_failed_jobs(project.id, pipeline.id, pipeline.updated_at)
+        if failed_jobs is None:
+            failed_jobs = self._fetch_failed_jobs(project, pipeline)
+            if pipeline.status in _SETTLED_PIPELINE_STATUSES:
+                cache.put_failed_jobs(
+                    project.id, pipeline.id, CachedPipeline(updated_at=pipeline.updated_at, failed_jobs=failed_jobs)
+                )
+        return PipelineState(id=pipeline.id, status=pipeline.status, url=pipeline.web_url, failed_jobs=failed_jobs)
+
+    def _fetch_failed_jobs(self, project: Project, pipeline: Pipeline) -> list[FailedJob]:
+        failed: typing.Final = [
+            FailedJob(
+                kind="job",
+                name=job.name,
+                stage=job.stage,
+                status=job.status,
+                allow_failure=job.allow_failure,
+                url=job.web_url,
+                failure_reason=job.failure_reason,
+            )
+            for job in self.api.failed_jobs(project.id, pipeline.id)
+        ]
+        failed.extend(
+            FailedJob(
+                kind="bridge",
+                name=bridge.name,
+                stage=bridge.stage,
+                status=bridge.status,
+                allow_failure=bridge.allow_failure,
+                url=bridge.web_url,
+                failure_reason=bridge.failure_reason,
+                downstream_pipeline_url=bridge.downstream_pipeline.web_url if bridge.downstream_pipeline else None,
+            )
+            for bridge in self.api.failed_bridges(project.id, pipeline.id)
+        )
+        return failed

release_scope/ioc.py

@@ -0,0 +1,51 @@
+import typing
+
+import httpware
+import modern_di
+from modern_di import Scope, providers
+
+from release_scope._gitlab import GitLabApi
+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
+
+
+def _build_gitlab_client(settings: Settings) -> httpware.Client:
+    return httpware.Client(
+        base_url=settings.gitlab.endpoint,
+        timeout=settings.request_timeout,
+        headers={"PRIVATE-TOKEN": settings.gitlab.token.get_secret_value()},
+        middleware=[httpware.Retry(retry_status_codes=_RETRY_STATUS_CODES)],
+        max_response_body_bytes=_MAX_RESPONSE_BODY_BYTES,
+    )
+
+
+def _close_client(client: httpware.Client) -> None:
+    client.close()
+
+
+class SettingsGroup(modern_di.Group):
+    settings = providers.ContextProvider(scope=Scope.APP, context_type=Settings)
+
+
+class ClientsGroup(modern_di.Group):
+    gitlab_client = providers.Factory(
+        scope=Scope.APP,
+        creator=_build_gitlab_client,
+        bound_type=None,
+        cache=providers.CacheSettings(finalizer=_close_client),
+    )
+    gitlab_api = providers.Factory(scope=Scope.APP, creator=GitLabApi, kwargs={"http": gitlab_client})
+
+
+class UseCasesGroup(modern_di.Group):
+    collect_use_case = providers.Factory(scope=Scope.APP, creator=CollectUseCase)
+
+
+ALL_GROUPS: typing.Final[list[type[modern_di.Group]]] = [SettingsGroup, ClientsGroup, UseCasesGroup]
+
+
+container: typing.Final = modern_di.Container(groups=ALL_GROUPS)

release_scope-0.1.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: release-scope
+Version: 0.1.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
+Author-email: Artur Shiriev <me@shiriev.ru>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
+Classifier: Typing :: Typed
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Dist: typer>=0.13
+Requires-Dist: pydantic>=2 ; python_full_version < '3.12'
+Requires-Dist: pydantic>=2.0.2 ; python_full_version == '3.12.*'
+Requires-Dist: pydantic>=2.8.2 ; python_full_version == '3.13.*'
+Requires-Dist: pydantic>=2.12 ; python_full_version >= '3.14'
+Requires-Dist: pydantic-settings>=2
+Requires-Dist: modern-di-typer>=3,<4
+Requires-Dist: httpx2>=2
+Requires-Dist: httpware[pydantic]>=0.15.0
+Requires-Python: >=3.11, <4
+Project-URL: Homepage, https://modern-python.org
+Project-URL: Repository, https://github.com/modern-python/release-scope
+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
+
+[![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/)
+[![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)
+
+`release-scope` collects what sits between production and the default branch across GitLab services: tags, MRs,
+Jira keys, 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.
+
+## 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.
+
+## 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_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).
+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}]}
+}
+```
+
+## 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.

release_scope-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+release_scope/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+release_scope/__main__.py,sha256=GR-KbxpdSSTxUOFnbf72zrlVe5B39svSQ1UsOLSE6P8,3577
+release_scope/_cache.py,sha256=vIa4IBjWWLprb8cJ9PxKukfeSjM-TDvKjlTcPqzfwSk,2886
+release_scope/_errors.py,sha256=HmKVxgb0-nNIuf0SXgqfKFFRm9cHwOiIDjSleNXgt48,330
+release_scope/_files.py,sha256=qbeLKAFe5VsGrOmexMZh4IP3mA3Mth9I3AghOVv7OYA,440
+release_scope/_gitlab.py,sha256=FvxLJ4myahfe3Ej0NnMBSp0BXRdwHffutgIJrVp1LG0,7813
+release_scope/_jira_keys.py,sha256=4cQ-sI2_6L8Bj-_JWJlUrg959nipGvji5lj7uoRooDw,606
+release_scope/_report.py,sha256=9Zxf09SCK10Xlx5mCMl5RRpbUkE4dArGxOCS0LSSI_k,1873
+release_scope/_rows.py,sha256=3BkSoGlJCc8uO2z3fFdW4lz9HQID0dMp7-_HsCUk1y0,1466
+release_scope/_settings.py,sha256=IN1Mbcy7Iq-UqN_pmfuZ8OjPwZN-JDoGoLWRIoi6JbI,1915
+release_scope/_use_case.py,sha256=oKObj6tNP8yTqr6yV-maVaMFQlLzSjS5ZUkhZzsu6Do,11060
+release_scope/ioc.py,sha256=obvstFVph9fHwpOGINpk5vRvuX1GxpPLPGs-g2U6vlI,1589
+release_scope/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+release_scope-0.1.0.dist-info/WHEEL,sha256=e4_1dyBeezi8ZjfxrZ3bnVOxFDa3ksqVqH0jTHkUZ3k,81
+release_scope-0.1.0.dist-info/entry_points.txt,sha256=94nlGzT5C-pL_trA6Wbjs3UL63mhSk_n_4AiBaHG718,63
+release_scope-0.1.0.dist-info/METADATA,sha256=eiX9ys_wU9g5x4pskBSHjArgBjHJrJQGOpqXhy30yYk,5441
+release_scope-0.1.0.dist-info/RECORD,,

release_scope-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.19
+Root-Is-Purelib: true
+Tag: py3-none-any

release_scope-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+release-scope = release_scope.__main__:main
+