alitheg commented on code in PR #1221: URL: https://github.com/apache/tooling-trusted-releases/pull/1221#discussion_r3189872695
########## atr/cle.py: ########## @@ -0,0 +1,237 @@ +# 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. + +Most of our column names match spec event types directly (eod, eom, eol). +The one translation: `archived` -> `endOfDistribution`. The column name +reflects ATR's action (the release left /dist/release); the spec name +describes the semantic. + +All three event constructors emit `published == effective`. For released +and endOfDistribution that matches the moment of recording. For cycle +events it's a stopgap until semver/calver lands; see _cycle_event. + +We don't emit endOfSupport, withdrawn, endOfMarketing, supersededBy, or +componentRenamed in v1 - spec-conformant absences for #912. +""" + +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 + +# Versioned schema URL. ECMA-428 is still draft, so this points at the +# tc54 working copy and may need updating when the spec ships. +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 five more we don't: +# endOfSupport, withdrawn, endOfMarketing, supersededBy, componentRenamed. +_RELEASE_EVENT: Final[str] = "released" +_END_OF_DISTRIBUTION_EVENT: Final[str] = "endOfDistribution" +_END_OF_DEVELOPMENT_EVENT: Final[str] = "endOfDevelopment" +_END_OF_MAINTENANCE_EVENT: Final[str] = "endOfMaintenance" +_END_OF_LIFE_EVENT: Final[str] = "endOfLife" + +# Maps internal column names to spec event types. +_CYCLE_EVENT_MAP: Final[tuple[tuple[str, str], ...]] = ( + ("eod", _END_OF_DEVELOPMENT_EVENT), + ("eom", _END_OF_MAINTENANCE_EVENT), + ("eol", _END_OF_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 _cycle_event( + project: sql.Project, + cycle_releases: list[sql.Release], + event_type: str, + effective: datetime.datetime, +) -> dict[str, Any]: + # Using effective for published until semver/calver lands - cycle phase + # transitions don't have their own publication timestamp yet. + return { + "type": event_type, + "effective": _iso(effective), + "published": _iso(effective), + "versions": [{"range": _vers_for_cycle(project, cycle_releases)}], + } + + +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), + } + + +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": _END_OF_DISTRIBUTION_EVENT, + "effective": _iso(release.archived), + "published": _iso(release.archived), + "versions": [{"range": _vers_literal(project, release.version)}], + } + + +def _events( + project: sql.Project, + cycles: list[sql.ProjectCycle], + releases: list[sql.Release], +) -> 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)) + + releases_by_cycle = _releases_by_cycle(releases) + for cycle in cycles: + cycle_releases = releases_by_cycle.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_releases, event_type, date_value)) + + # Sort ascending by effective date so id assignment is stable for a given Review Comment: > Event IDs must be assigned as auto-incrementing integers in the order events are added (not by effective date). Aha. This could be the argument for having a CLE events table... -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
