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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: release-scope
-Version: 0.1.0
+Version: 0.2.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
@@ -57,7 +57,10 @@ uvx release-scope collect --group team/backend --output report.json --cache cach
 ```
 
 `--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.
+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.
 
 ## Configuration
 
@@ -92,6 +95,24 @@ One row, trimmed:
 }
 ```
 
+## 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;
+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.
+
+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

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

@@ -24,7 +24,10 @@ uvx release-scope collect --group team/backend --output report.json --cache cach
 ```
 
 `--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.
+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.
 
 ## Configuration
 
@@ -59,6 +62,24 @@ One row, trimmed:
 }
 ```
 
+## 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;
+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.
+
+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

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

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

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

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

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

@@ -3,12 +3,15 @@ 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._render import render_markdown
+from release_scope._report import Report
 from release_scope._settings import Settings, load_settings
 from release_scope._use_case import CollectUseCase
 
@@ -91,11 +94,29 @@ def _collect_command(  # noqa: PLR0913, PLR0917
     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)
+        typer.echo(f"Error: {service.error}", err=True)
     if failed:
         raise typer.Exit(code=1)
 
 
+@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:
+        typer.echo(f"Error: Cannot read report {report_path}: {type(exc).__name__}.", err=True)
+        raise typer.Exit(code=ConfigError.exit_code) from exc
+    try:
+        write_text_atomic(output, render_markdown(report))
+    except OSError as exc:
+        typer.echo(f"Error: Cannot write page {output}: {type(exc).__name__}.", err=True)
+        raise typer.Exit(code=ReleaseScopeError.exit_code) from exc
+    typer.echo(f"{len(report.services)} services -> {output}", err=True)
+
+
 def main() -> None:
     with ioc.container:
         MAIN_APP()

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

@@ -15,3 +15,9 @@ class AuthError(ReleaseScopeError):
 
 class GitLabError(ReleaseScopeError):
     exit_code: typing.ClassVar[int] = 4
+
+    def __init__(self, message: str, *, resource: str, status: int | None = None, reason: str = "") -> None:
+        super().__init__(message)
+        self.resource = resource
+        self.status = status
+        self.reason = reason

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

@@ -2,7 +2,7 @@ import dataclasses
 import datetime
 import math
 import typing
-from urllib.parse import quote
+from urllib.parse import quote, unquote
 
 import httpware
 import pydantic
@@ -22,6 +22,8 @@ class Project(pydantic.BaseModel):
     path_with_namespace: str
     web_url: str
     default_branch: str | None = None
+    builds_access_level: str | None = None
+    environments_access_level: str | None = None
 
 
 class Deployable(pydantic.BaseModel):
@@ -133,14 +135,19 @@ 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."
-        )
+Resource: typing.TypeAlias = typing.Literal[
+    "group", "project", "deployments", "pipelines", "repository", "merge_requests"
+]
+
+
+def _translate(exc: httpware.ClientError, *, url: str, resource: Resource) -> Exception:
+    if isinstance(exc, httpware.UnauthorizedError):
+        return AuthError("GitLab rejected the token (401). Check that it is valid and not expired.")
     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__}.")
+        status: typing.Final = exc.response.status_code
+        return GitLabError(f"GitLab returned {status} for {unquote(url)}.", resource=resource, status=status)
+    reason: typing.Final = type(exc).__name__
+    return GitLabError(f"GitLab request {unquote(url)} failed: {reason}.", resource=resource, reason=reason)
 
 
 def _quote(value: str) -> str:
@@ -151,11 +158,11 @@ def _quote(value: str) -> str:
 class GitLabApi:
     http: httpware.Client
 
-    def _get(self, url: str, params: dict[str, typing.Any], model: type[_ModelT]) -> _ModelT:
+    def _get(self, url: str, params: dict[str, typing.Any], model: type[_ModelT], *, resource: Resource) -> _ModelT:
         try:
             return self.http.get(url, params=params, response_model=model)
         except httpware.ClientError as exc:
-            raise _translate(exc, url=url) from exc
+            raise _translate(exc, url=url, resource=resource) from exc
 
     def _pages(
         self,
@@ -163,6 +170,7 @@ class GitLabApi:
         params: dict[str, typing.Any],
         model: type[pydantic.RootModel[list[_ModelT]]],
         *,
+        resource: Resource,
         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)
@@ -173,7 +181,7 @@ class GitLabApi:
                     url, params={**params, "per_page": _PER_PAGE, "page": page}, response_model=model
                 )
             except httpware.ClientError as exc:
-                raise _translate(exc, url=url) from exc
+                raise _translate(exc, url=url, resource=resource) from exc
             items.extend(batch.root)
             if not response.headers.get("x-next-page"):
                 break
@@ -184,13 +192,14 @@ class GitLabApi:
         return items, False
 
     def get_project(self, path: str) -> Project:
-        return self._get(f"{_API}/projects/{_quote(path)}", {}, Project)
+        return self._get(f"{_API}/projects/{_quote(path)}", {}, Project, resource="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,
+            resource="group",
         )
         return projects
 
@@ -199,11 +208,12 @@ class GitLabApi:
             f"{_API}/projects/{project_id}/deployments",
             {"environment": environment, "status": "success", "order_by": "id", "sort": "desc", "per_page": 1},
             _Deployments,
+            resource="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)
+        return self._pages(f"{_API}/projects/{project_id}/repository/tags", {}, _Tags, resource="repository")
 
     def list_first_parent_commits(
         self, project_id: int, ref_range: str, *, max_items: int
@@ -212,6 +222,7 @@ class GitLabApi:
             f"{_API}/projects/{project_id}/repository/commits",
             {"ref_name": ref_range, "first_parent": "true"},
             _Commits,
+            resource="repository",
             max_items=max_items,
         )
 
@@ -222,12 +233,16 @@ class GitLabApi:
             f"{_API}/projects/{project_id}/merge_requests",
             {"state": "merged", "target_branch": target_branch, "updated_after": updated_after.isoformat()},
             _MergeRequests,
+            resource="merge_requests",
         )
         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
+            f"{_API}/projects/{project_id}/repository/commits/{sha}/merge_requests",
+            {},
+            _MergeRequests,
+            resource="merge_requests",
         )
         return merge_requests
 
@@ -236,6 +251,7 @@ class GitLabApi:
             f"{_API}/projects/{project_id}/pipelines",
             {"ref": ref, "source": "push", "updated_after": updated_after.isoformat()},
             _Pipelines,
+            resource="pipelines",
         )
         return pipelines
 
@@ -244,18 +260,25 @@ class GitLabApi:
             f"{_API}/projects/{project_id}/pipelines",
             {"ref": ref, "order_by": "id", "sort": "desc", "per_page": 1},
             _Pipelines,
+            resource="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
+            f"{_API}/projects/{project_id}/pipelines/{pipeline_id}/jobs",
+            {"scope[]": "failed"},
+            _Jobs,
+            resource="pipelines",
         )
         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
+            f"{_API}/projects/{project_id}/pipelines/{pipeline_id}/bridges",
+            {"scope[]": "failed"},
+            _Bridges,
+            resource="pipelines",
         )
         return bridges

release_scope-0.2.0/release_scope/_messages.py

@@ -0,0 +1,47 @@
+import http
+import typing
+
+from release_scope._errors import GitLabError
+from release_scope._gitlab import Project
+
+
+_RESOURCES: typing.Final[dict[str, tuple[str, tuple[str, ...]]]] = {
+    "deployments": ("deployments", ("Environments", "CI/CD")),
+    "pipelines": ("pipelines", ("CI/CD",)),
+    "repository": ("the repository", ("Repository",)),
+    "merge_requests": ("merge requests", ("Merge requests",)),
+}
+_PLURAL_FEATURES: typing.Final = frozenset({"Environments", "Merge requests"})
+
+
+def _feature_setting(project: Project, feature: str) -> str:
+    return f"{project.web_url}/edit#js-shared-permissions → Visibility, project features, permissions → {feature}"
+
+
+def explain_failure(project: Project, error: GitLabError) -> str:
+    name: typing.Final = project.path_with_namespace
+    resource, features = _RESOURCES.get(error.resource, ("project data", ()))
+    if error.status is None:
+        return f"{name}: GitLab request for {resource} failed ({error.reason})."
+    if error.status != http.HTTPStatus.FORBIDDEN:
+        return f"{name}: GitLab returned {error.status} for {resource}."
+    checks: typing.Final = [
+        f"- {feature} {'are' if feature in _PLURAL_FEATURES else 'is'} enabled: {_feature_setting(project, feature)}"
+        for feature in features
+    ]
+    checks.append(f"- the token's user has a role that can read them: {project.web_url}/-/project_members")
+    return "\n".join([f"{name}: GitLab denied access to {resource} (403). Check that:", *checks])
+
+
+def skip_reason(project: Project) -> str | None:
+    if project.builds_access_level == "disabled":
+        return (
+            "CI/CD is disabled, so it has no pipelines or deployments. "
+            f"Enable it at {_feature_setting(project, 'CI/CD')}."
+        )
+    if project.environments_access_level == "disabled":
+        return (
+            "Environments are disabled, so it has no deployments. "
+            f"Enable them at {_feature_setting(project, 'Environments')}."
+        )
+    return None

release_scope-0.2.0/release_scope/_render.py

@@ -0,0 +1,251 @@
+import collections.abc
+import datetime
+import html
+import typing
+
+from release_scope._report import EnvironmentState, FailedJob, PipelineState, Report, Row, Service, TagRef
+
+
+_STATUS_ICONS: typing.Final = {
+    "success": "✅",
+    "failed": "❌",
+    "created": "🔄",
+    "waiting_for_resource": "🔄",
+    "preparing": "🔄",
+    "pending": "🔄",
+    "running": "🔄",
+    "scheduled": "🔄",
+    "canceled": "⏭",
+    "skipped": "⏭",
+    "manual": "⏭",
+}
+_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
+
+
+def _inline(value: str) -> str:
+    return html.escape(value, quote=False).replace("|", "\\|").replace("[", "\\[").replace("]", "\\]")
+
+
+def _cell(value: str) -> str:
+    return _inline(value).replace("\r\n", "<br>").replace("\n", "<br>")
+
+
+def _link(label: str, url: str | None) -> str:
+    if not url:
+        return label
+    return f"[{label}]({url.replace(' ', '%20').replace(')', '%29').replace('|', '%7C')})"
+
+
+def _icon(status: str) -> str:
+    return _STATUS_ICONS.get(status, f"`{status}`")
+
+
+def _plural(count: int, noun: str) -> str:
+    return f"{count} {noun}" if count == 1 else f"{count} {noun}s"
+
+
+def _nonzero(separator: str, parts: collections.abc.Iterable[tuple[int, str]]) -> str:
+    return separator.join(text for count, text in parts if count)
+
+
+def _table(
+    header: collections.abc.Sequence[str], rows: collections.abc.Iterable[collections.abc.Sequence[str]]
+) -> list[str]:
+    lines: typing.Final = [f"| {' | '.join(header)} |", f"|{'---|' * len(header)}"]
+    lines.extend(f"| {' | '.join(row)} |" for row in rows)
+    return lines
+
+
+def _collapsed(summary: str, body: list[str]) -> list[str]:
+    return ["<details>", f"<summary>{summary}</summary>", "", *body, "", "</details>", ""]
+
+
+def _state(service: Service) -> int | None:
+    if service.error:
+        return _FAILED
+    if service.rows:
+        return _PENDING
+    return _SKIPPED if service.warnings else None
+
+
+def _environment_names(report: Report) -> list[str]:
+    names: dict[str, None] = {report.production_environment: None}
+    for service in report.services:
+        names.update((item.name, None) for item in service.environments)
+    return list(names)
+
+
+def _environment(service: Service, name: str) -> EnvironmentState | None:
+    return next((item for item in service.environments if item.name == name), None)
+
+
+def _environment_ref(environment: EnvironmentState | None) -> str:
+    return _link(_cell(environment.ref), environment.deployment_url) if environment else "—"
+
+
+def _failure_counts(service: Service) -> str:
+    pipelines: typing.Final = [row.main_pipeline for row in service.rows] + [
+        tag.pipeline for row in service.rows for tag in row.tags
+    ]
+    jobs: typing.Final = [job for pipeline in pipelines if pipeline for job in pipeline.failed_jobs]
+    allowed: typing.Final = sum(1 for job in jobs if job.allow_failure)
+    blocking: typing.Final = len(jobs) - allowed
+    return _nonzero(" · ", [(blocking, f"❌ {blocking}"), (allowed, f"⚠️ {allowed} allowed")])
+
+
+def _pending(service: Service) -> str:
+    state: typing.Final = _state(service)
+    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}"
+
+
+def _summary_row(service: Service, environments: list[str]) -> list[str]:
+    return [
+        _link(_cell(service.project), service.project_url),
+        *(_environment_ref(_environment(service, name)) for name in environments),
+        _pending(service),
+        _failure_counts(service),
+    ]
+
+
+def _job(job: FailedJob) -> str:
+    text: str = _link(_cell(job.name), job.url)
+    if job.allow_failure:
+        text += " (allowed)"
+    if job.downstream_pipeline_url:
+        text += f" → {_link('child', job.downstream_pipeline_url)}"
+    return text
+
+
+def _jobs(pipeline: PipelineState) -> str:
+    return ", ".join(_job(job) for job in pipeline.failed_jobs)
+
+
+def _main_pipeline(pipeline: PipelineState) -> str:
+    text: typing.Final = f"main {_icon(pipeline.status)} {_link(str(pipeline.id), pipeline.url)}"
+    return f"{text}: {_jobs(pipeline)}" if pipeline.failed_jobs else text
+
+
+def _tag(tag: TagRef) -> str:
+    if tag.pipeline is None:
+        return f"{_link(_cell(tag.name), tag.url)} ⚠️ no pipeline"
+    return f"{_link(_cell(tag.name), tag.pipeline.url)} {_icon(tag.pipeline.status)}"
+
+
+def _reference(label: str, url: str | None, title: str, author: str | None) -> str:
+    return f"{_link(label, url)} {_cell(title)}" + (f" · {_cell(author)}" if author else "")
+
+
+def _merge_requests_or_commits(row: Row) -> str:
+    if row.merge_requests:
+        return "<br>".join(
+            _reference(f"!{item.iid}", item.url, item.title, f"@{item.author}" if item.author else None)
+            for item in row.merge_requests
+        )
+    return "<br>".join(_reference(f"`{item.short_sha}`", item.url, item.title, item.author) for item in row.commits)
+
+
+def _failed_jobs(row: Row) -> str:
+    parts: typing.Final = [_main_pipeline(row.main_pipeline)] if row.main_pipeline else []
+    parts.extend(
+        f"tag {_cell(tag.name)}: {_jobs(tag.pipeline)}" for tag in row.tags if tag.pipeline and tag.pipeline.failed_jobs
+    )
+    return "<br>".join(parts)
+
+
+def _row(row: Row) -> list[str]:
+    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),
+        ", ".join(_cell(name) for name in row.environments),
+        _failed_jobs(row),
+    ]
+
+
+def _counts(service: Service) -> str:
+    merge_requests: typing.Final = len({item.iid for row in service.rows for item in row.merge_requests})
+    commits: typing.Final = sum(1 for row in service.rows if row.kind == "commit")
+    return _nonzero(
+        ", ", [(merge_requests, _plural(merge_requests, "merge request")), (commits, _plural(commits, "direct commit"))]
+    )
+
+
+def _rows_section(service: Service, production: str) -> 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)
+    since: typing.Final = f" since {_inline(production_state.ref)}" if production_state else ""
+    return [
+        " · ".join([*environments, _counts(service)]),
+        "",
+        *_collapsed(
+            f"{_plural(len(service.rows), 'change')}{since}",
+            _table(_ROW_HEADER, (_row(row) for row in service.rows)),
+        ),
+    ]
+
+
+def _service_section(service: Service, production: str) -> 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)}", ""))
+    if service.rows:
+        lines.extend(_rows_section(service, production))
+    return lines
+
+
+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")
+    lines: typing.Final = [
+        "# Release scope",
+        "",
+        (
+            f"Collected {collected} UTC. Changes run from the commit on `{_inline(production)}` "
+            "to the head of the default branch."
+        ),
+        "",
+        _LEGEND,
+        "",
+    ]
+    if not report.services:
+        lines.append("No services were collected.")
+        return "\n".join(lines) + "\n"
+
+    attention: typing.Final = sorted(
+        (service for service in report.services if _state(service) is not None),
+        key=lambda service: (_state(service), service.project),
+    )
+    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)), ""])
+    else:
+        lines.extend(["All services are up to date.", ""])
+    if up_to_date:
+        lines.extend(
+            _collapsed(
+                f"{_plural(len(up_to_date), 'service')} up to date",
+                _table(
+                    ["Service", _cell(production)],
+                    (
+                        [_link(_cell(item.project), item.project_url), _environment_ref(_environment(item, production))]
+                        for item in up_to_date
+                    ),
+                ),
+            )
+        )
+    for service in attention:
+        lines.extend(_service_section(service, production))
+    return "\n".join(lines).rstrip("\n") + "\n"

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

@@ -1,13 +1,15 @@
 import collections.abc
 import dataclasses
 import datetime
+import http
 import typing
 from urllib.parse import quote
 
 from release_scope._cache import Cache, CachedPipeline
-from release_scope._errors import GitLabError
+from release_scope._errors import AuthError, GitLabError
 from release_scope._gitlab import Commit, Deployment, GitLabApi, MergeRequest, Pipeline, Project
 from release_scope._jira_keys import extract_jira_keys
+from release_scope._messages import explain_failure, skip_reason
 from release_scope._report import (
     CommitRef,
     EnvironmentState,
@@ -27,6 +29,15 @@ from release_scope._settings import Settings
 _SETTLED_PIPELINE_STATUSES: typing.Final = frozenset({"success", "failed", "canceled", "skipped"})
 
 
+def _resolution_error(error: GitLabError, target: str) -> Exception:
+    if error.status == http.HTTPStatus.FORBIDDEN:
+        return AuthError(
+            f"GitLab denied access to {target} (403). "
+            "Check that the token has the 'read_api' scope and that its user can see it."
+        )
+    return error
+
+
 def _environment_state(name: str, deployment: Deployment) -> EnvironmentState:
     return EnvironmentState(
         name=name,
@@ -79,7 +90,11 @@ class CollectUseCase:
             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))
+                    Service(
+                        project=project.path_with_namespace,
+                        project_url=project.web_url,
+                        error=explain_failure(project, exc),
+                    )
                 )
         return Report(
             collected_at=datetime.datetime.now(datetime.UTC),
@@ -96,10 +111,16 @@ class CollectUseCase:
     ) -> 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
+            try:
+                listed = self.api.list_group_projects(group, include_subgroups=include_subgroups)
+            except GitLabError as exc:
+                raise _resolution_error(exc, f"group '{group}'") from exc
+            resolved.update((project.id, project) for project in listed)
         for path in projects:
-            project = self.api.get_project(path)
+            try:
+                project = self.api.get_project(path)
+            except GitLabError as exc:
+                raise _resolution_error(exc, f"project '{path}'") from exc
             resolved[project.id] = project
         return sorted(resolved.values(), key=lambda item: item.path_with_namespace)
 
@@ -107,6 +128,10 @@ class CollectUseCase:
         service: typing.Final = Service(
             project=project.path_with_namespace, project_url=project.web_url, default_branch=project.default_branch
         )
+        reason: typing.Final = skip_reason(project)
+        if reason is not None:
+            service.warnings.append(reason)
+            return service
         for name in self.settings.environments:
             deployment = self.api.latest_deployment(project.id, name)
             if deployment is not None: