You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tooling.apache.org by ar...@apache.org on 2026/05/05 09:38:44 UTC
(tooling-trusted-releases) 01/01: #912/#914 - generate CLE doc from project lifecycle
This is an automated email from the ASF dual-hosted git repository.
alitheg pushed a commit to branch project_cycle_model
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git
commit 42db67179e624151ff161f71fdda62b60140ae0e
Author: Alastair McFarlane <ar...@apache.org>
AuthorDate: Mon May 4 18:24:34 2026 +0100
#912/#914 - generate CLE doc from project lifecycle
---
atr/api/__init__.py | 55 ++++++++++++
atr/cle.py | 235 ++++++++++++++++++++++++++++++++++++++++++++++++++++
atr/db/__init__.py | 27 ++++++
3 files changed, 317 insertions(+)
diff --git a/atr/api/__init__.py b/atr/api/__init__.py
index af2db007..6bc3db9b 100644
--- a/atr/api/__init__.py
+++ b/atr/api/__init__.py
@@ -29,6 +29,7 @@ import sqlmodel
import werkzeug.exceptions as exceptions
import atr.blueprints.api as api
+import atr.cle as cle
import atr.config as config
import atr.db as db
import atr.db.interaction as interaction
@@ -174,6 +175,60 @@ async def checks_ongoing(
).model_dump(mode="json"), 200
+@api.typed
+async def cle_project(
+ _cle_project: Literal["cle/project"],
+ project_key: safe.ProjectKey,
+) -> DictResponse:
+ """
+ URL: GET /cle/project/<project_key>
+
+ Generate an ECMA-428 Common Lifecycle Enumeration document covering every
+ cycle and release of a project. This is the canonical form per the spec -
+ one document per component. The body is the raw CLE document, with no ATR
+ envelope, so it can be consumed directly by tooling that expects spec-shaped
+ CLE JSON.
+ """
+ async with db.session() as data:
+ project = await data.project(key=str(project_key)).demand(
+ exceptions.NotFound(f"Project '{project_key!s}' was not found")
+ )
+ cycles = await data.project_cycle(project_key=str(project_key)).all()
+ releases = await data.release(phase=sql.ReleasePhase.RELEASE, project_key=str(project_key)).all()
+ return cle.project_document(project, cycles, releases, now=datetime.datetime.now(datetime.UTC)), 200
+
+
+@api.typed
+async def cle_release(
+ _cle_release: Literal["cle/release"],
+ project_key: safe.ProjectKey,
+ version_key: safe.VersionKey,
+) -> DictResponse:
+ """
+ URL: GET /cle/release/<project_key>/<version_key>
+
+ Generate a CLE document filtered to a single release. This is a derived
+ view rather than a spec form - the document still has the per-component
+ shape ECMA-428 prescribes, but only includes events that touch this
+ release: its own released and archived events, plus the lifecycle events
+ of the cycle it belongs to.
+ """
+ async with db.session() as data:
+ release_obj = await data.release(
+ project_key=str(project_key),
+ version=str(version_key),
+ _cycle=True,
+ ).demand(exceptions.NotFound(f"Release '{project_key!s}-{version_key!s}' was not found"))
+ if release_obj.phase != sql.ReleasePhase.RELEASE:
+ raise exceptions.NotFound(f"Release '{project_key!s}-{version_key!s}' is not released")
+ return cle.release_document(
+ release_obj.project,
+ release_obj.cycle,
+ release_obj,
+ now=datetime.datetime.now(datetime.UTC),
+ ), 200
+
+
@api.typed
@quart_schema.validate_response(models.api.CommitteeGetResults, 200)
async def committee_get(
diff --git a/atr/cle.py b/atr/cle.py
new file mode 100644
index 00000000..3afd3978
--- /dev/null
+++ b/atr/cle.py
@@ -0,0 +1,235 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""ECMA-428 Common Lifecycle Enumeration document generator.
+
+Internal column names follow ATR's intent (`eom`, `archived`); the spec wire
+format calls these `endOfSupport` and `endOfDistribution` respectively. The
+translation happens here so the rest of the codebase can keep its own naming.
+
+We don't emit `withdrawn`, `endOfMarketing`, `supersededBy`, or `componentRenamed`
+in v1 - they're spec-conformant absences. See decision #12 in the discussion doc.
+"""
+
+from __future__ import annotations
+
+import datetime
+from typing import TYPE_CHECKING, Any, Final
+
+import atr.models.sql as sql
+
+if TYPE_CHECKING:
+ from collections.abc import Iterable
+
+# The spec ships a versioned schema URL we should point to. The drafts use
+# example.com placeholders; we'll drop in the real URL when ECMA-428 stabilises.
+CLE_SCHEMA_URL: Final[str] = "https://ecma-tc54.github.io/ECMA-428/cle.v1.0.0.schema.json"
+
+# CLE event types we currently emit. The spec defines four more we don't:
+# withdrawn, endOfMarketing, supersededBy, componentRenamed.
+_RELEASE_EVENT: Final[str] = "released"
+_DISTRIBUTION_EVENT: Final[str] = "endOfDistribution"
+_DEVELOPMENT_EVENT: Final[str] = "endOfDevelopment"
+_SUPPORT_EVENT: Final[str] = "endOfSupport"
+_LIFE_EVENT: Final[str] = "endOfLife"
+
+# Maps internal column names to spec event types.
+_CYCLE_EVENT_MAP: Final[tuple[tuple[str, str], ...]] = (
+ ("eod", _DEVELOPMENT_EVENT),
+ ("eom", _SUPPORT_EVENT),
+ ("eol", _LIFE_EVENT),
+)
+
+
+def project_document(
+ project: sql.Project,
+ cycles: Iterable[sql.ProjectCycle],
+ releases: Iterable[sql.Release],
+ *,
+ now: datetime.datetime,
+) -> dict[str, Any]:
+ """Generate a CLE document covering every event for a project.
+
+ This is the canonical form per ECMA-428: one document per component.
+ """
+ cycles_list = list(cycles)
+ releases_list = list(releases)
+ return _document(project, cycles_list, releases_list, now=now)
+
+
+def release_document(
+ project: sql.Project,
+ cycle: sql.ProjectCycle,
+ release: sql.Release,
+ *,
+ now: datetime.datetime,
+) -> dict[str, Any]:
+ """Generate a CLE document filtered to a single release.
+
+ This is a derived view, not a spec form. The document still has the
+ component-level shape ECMA-428 prescribes, but only includes events
+ touching this release: its own released/archived events, plus the
+ lifecycle events of the cycle it belongs to.
+ """
+ return _document(project, [cycle], [release], now=now)
+
+
+def _document(
+ project: sql.Project,
+ cycles: list[sql.ProjectCycle],
+ releases: list[sql.Release],
+ *,
+ now: datetime.datetime,
+) -> dict[str, Any]:
+ return {
+ "$schema": CLE_SCHEMA_URL,
+ "identifier": _identifier(project),
+ "updatedAt": _iso(now),
+ "events": _events(project, cycles, releases, now=now),
+ }
+
+
+def _events(
+ project: sql.Project,
+ cycles: list[sql.ProjectCycle],
+ releases: list[sql.Release],
+ *,
+ now: datetime.datetime,
+) -> list[dict[str, Any]]:
+ """Build the events list, ordered by effective date then by id descending."""
+
+ raw: list[dict[str, Any]] = []
+
+ for release in releases:
+ if release.released is not None:
+ raw.append(_released_event(release))
+ if release.archived is not None:
+ raw.append(_end_of_distribution_event(project, release))
+
+ cycle_releases = _releases_by_cycle(releases)
+ for cycle in cycles:
+ cycle_versions = cycle_releases.get(cycle.cycle_key, [])
+ for column, event_type in _CYCLE_EVENT_MAP:
+ date_value = getattr(cycle, column)
+ if date_value is not None:
+ raw.append(_cycle_event(project, cycle_versions, event_type, date_value, now))
+
+ # Sort ascending by effective date so id assignment is stable for a given
+ # input set. Then emit descending by id, per ECMA-428 Annex B.
+ raw.sort(key=lambda event: (event["effective"], event["type"]))
+ for index, event in enumerate(raw, start=1):
+ event["id"] = index
+ raw.reverse()
+ return raw
+
+
+def _identifier(project: sql.Project) -> str:
+ """Render the project as a Package-URL.
+
+ `pkg:apache/<project_key>` is the simplest form. Per-distribution PURLs
+ (`pkg:maven/...`, `pkg:pypi/...`) belong on the artifact catalog (#911),
+ not on the lifecycle doc. This may change with outcome of https://github.com/package-url/purl-spec/issues/516
+ """
+ return f"pkg:apache/{project.key}"
+
+
+def _released_event(release: sql.Release) -> dict[str, Any]:
+ if release.released is None:
+ raise ValueError("released event requires release.released to be set")
+ return {
+ "type": _RELEASE_EVENT,
+ "effective": _iso(release.released),
+ "published": _iso(release.released),
+ "version": release.version,
+ }
+
+
+def _end_of_distribution_event(project: sql.Project, release: sql.Release) -> dict[str, Any]:
+ if release.archived is None:
+ raise ValueError("endOfDistribution event requires release.archived to be set")
+ return {
+ "type": _DISTRIBUTION_EVENT,
+ "effective": _iso(release.archived),
+ "published": _iso(release.archived),
+ "versions": [{"range": _vers_literal(project, release.version)}],
+ }
+
+
+def _cycle_event(
+ project: sql.Project,
+ cycle_releases: list[sql.Release],
+ event_type: str,
+ effective: datetime.datetime,
+ now: datetime.datetime,
+) -> dict[str, Any]:
+ return {
+ "type": event_type,
+ "effective": _iso(effective),
+ "published": _iso(now),
+ "versions": [{"range": _vers_for_cycle(project, cycle_releases)}],
+ }
+
+
+def _releases_by_cycle(releases: list[sql.Release]) -> dict[str, list[sql.Release]]:
+ grouped: dict[str, list[sql.Release]] = {}
+ for release in releases:
+ grouped.setdefault(release.cycle_key, []).append(release)
+ return grouped
+
+
+def _vers_for_cycle(project: sql.Project, cycle_releases: list[sql.Release]) -> str:
+ """Render a VERS range for every version in a cycle.
+
+ For a cycle with no releases yet we emit a wildcard - the lifecycle event
+ applies to all versions in the (currently empty) cycle. With releases, we
+ emit a literal pipe-delimited list of every version, which is correct
+ regardless of version_method but verbose for large cycles. Once semver
+ projects exist, this can return a proper range like
+ `vers:semver/>=2.0.0|<3.0.0` derived from cycle_match.
+ """
+ scheme = _vers_scheme(project)
+ if not cycle_releases:
+ return f"vers:{scheme}/*"
+ constraints = "|".join(f"={r.version}" for r in cycle_releases)
+ return f"vers:{scheme}/{constraints}"
+
+
+def _vers_literal(project: sql.Project, version: str) -> str:
+ """Render a VERS range matching exactly one version."""
+ return f"vers:{_vers_scheme(project)}/={version}"
+
+
+def _vers_scheme(project: sql.Project) -> str:
+ """Pick a VERS versioning scheme for a project.
+
+ `generic` is the safe default - it doesn't constrain the version syntax.
+ For semver/calver projects we could pick `semver`/`calver` once the
+ cycle_match work lands, but for now every project is `simple` and
+ `generic` carries no false claims about ordering semantics.
+ """
+ if project.version_method == sql.VersionMethod.SEMVER:
+ return "semver"
+ return "generic"
+
+
+def _iso(value: datetime.datetime) -> str:
+ """Render a UTC datetime as ISO 8601 with a Z suffix."""
+ if value.tzinfo is None:
+ value = value.replace(tzinfo=datetime.UTC)
+ else:
+ value = value.astimezone(datetime.UTC)
+ return value.isoformat().replace("+00:00", "Z")
diff --git a/atr/db/__init__.py b/atr/db/__init__.py
index b31a4131..8bf64082 100644
--- a/atr/db/__init__.py
+++ b/atr/db/__init__.py
@@ -429,6 +429,30 @@ class Session(sqlalchemy.ext.asyncio.AsyncSession):
return Query(self, query)
+ def project_cycle(
+ self,
+ cycle_key: Opt[str] = NOT_SET,
+ project_key: Opt[str] = NOT_SET,
+ cycle: Opt[str] = NOT_SET,
+ _project: bool = False,
+ _releases: bool = False,
+ ) -> Query[sql.ProjectCycle]:
+ query = sqlmodel.select(sql.ProjectCycle)
+
+ if is_defined(cycle_key):
+ query = query.where(sql.ProjectCycle.cycle_key == cycle_key)
+ if is_defined(project_key):
+ query = query.where(sql.ProjectCycle.project_key == project_key)
+ if is_defined(cycle):
+ query = query.where(sql.ProjectCycle.cycle == cycle)
+
+ if _project:
+ query = query.options(joined_load(sql.ProjectCycle.project))
+ if _releases:
+ query = query.options(select_in_load(sql.ProjectCycle.releases))
+
+ return Query(self, query)
+
def public_signing_key(
self,
fingerprint: Opt[str] = NOT_SET,
@@ -527,6 +551,7 @@ class Session(sqlalchemy.ext.asyncio.AsyncSession):
_project_release_policy: bool = False,
_revisions: bool = False,
_distributions: bool = False,
+ _cycle: bool = False,
) -> Query[sql.Release]:
query = sqlmodel.select(sql.Release)
@@ -566,6 +591,8 @@ class Session(sqlalchemy.ext.asyncio.AsyncSession):
query = query.options(select_in_load(sql.Release.revisions))
if _distributions:
query = query.options(joined_load(sql.Release.distributions))
+ if _cycle:
+ query = query.options(joined_load(sql.Release.cycle))
return Query(self, query)
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@tooling.apache.org
For additional commands, e-mail: commits-help@tooling.apache.org