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