gowalk-cicd 1.0.0

package/action/prompts/generate_dependent_fields.prompt.yml

@@ -0,0 +1,78 @@
+name: Generate ASC Dependent Fields
+description: ASO-optimized name/subtitle/keywords/promotionalText/whatsNew derived from authoritative descriptions (Phase 2)
+model: openai/gpt-4o
+modelParameters:
+  temperature: 0.7
+  max_tokens: 8000
+messages:
+  - role: system
+    content: |
+      You are a senior App Store Optimization (ASO) specialist and localization expert.
+      Given an iOS app's source-code fingerprint, authoritative per-locale descriptions,
+      and a list of empty metadata fields per locale, generate ASO-optimized,
+      guideline-compliant content.
+
+      STRICT RULES per field:
+      - name: <=30 chars. Include primary keyword naturally. No "app"/"free"/"best". No trademarks.
+      - subtitle: <=30 chars. Complement name WITHOUT repeating its words. Secondary keyword.
+      - keywords: <=100 chars TOTAL. Comma-separated NO SPACES after commas. Do not repeat words
+        from name or subtitle (Apple indexes them separately). No app category, no "app", no trademarks.
+      - promotionalText: <=170 chars. Current benefit or seasonal hook.
+      - whatsNew: <=4000 chars. Release notes bullets. If locale has no prior notes,
+        default to performance/bug-fix/security boilerplate.
+
+      DEPENDENCY RULES:
+      The `description` field for each locale is PROVIDED as authoritative context.
+      For every dependent field you generate, you MUST:
+        - promotionalText: extract the single strongest benefit from description's
+          first sentence; paraphrase to <=170 chars. Do NOT invent new value props.
+        - keywords: extract high-intent nouns/phrases present in description;
+          avoid words already in name/subtitle.
+        - subtitle: state a secondary benefit from description paragraph 2;
+          must not duplicate name tokens.
+      name and whatsNew are INDEPENDENT — generate without description context.
+
+      CRITICAL:
+      - You receive a JSON list of `empty_fields` per locale. ONLY generate the listed fields
+        for the listed locales. Do not generate fields that were not requested.
+      - Never generate a `description` field — descriptions are authoritative input, not output.
+      - Translate faithfully for each locale's market - not literal word-for-word. Adapt ASO
+        keywords to local search behavior. Respect character limits in the target script
+        (CJK char counts differ from byte counts).
+      - Never output URLs (privacyPolicyUrl, supportUrl, marketingUrl, privacyChoicesUrl).
+      - Output STRICT JSON matching the schema - no markdown, no commentary.
+
+  - role: user
+    content: |
+      APP CONTEXT:
+      {{app_context}}
+
+      DESCRIPTIONS BY LOCALE (AUTHORITATIVE):
+      {{descriptions_by_locale}}
+
+      EMPTY FIELDS TO FILL:
+      {{empty_fields}}
+
+      Generate now.
+
+responseFormat: json_schema
+jsonSchema:
+  name: ascDependentFields
+  strict: true
+  schema:
+    type: object
+    additionalProperties: false
+    required: [localizations]
+    properties:
+      localizations:
+        type: object
+        description: "Keyed by Apple locale code (en-US, ja, de-DE, ...)"
+        additionalProperties:
+          type: object
+          additionalProperties: false
+          properties:
+            name:            { type: string, maxLength: 30 }
+            subtitle:        { type: string, maxLength: 30 }
+            keywords:        { type: string, maxLength: 100 }
+            promotionalText: { type: string, maxLength: 170 }
+            whatsNew:        { type: string, maxLength: 4000 }

package/action/prompts/generate_descriptions.prompt.yml

@@ -0,0 +1,59 @@
+name: Generate ASC Descriptions
+description: ASO-optimized App Store long descriptions per locale (Phase 1)
+model: openai/gpt-4o
+modelParameters:
+  temperature: 0.7
+  max_tokens: 8000
+messages:
+  - role: system
+    content: |
+      You are a senior App Store Optimization (ASO) specialist and localization expert.
+      Given an iOS app's source-code fingerprint and a list of locales that need a
+      long description, generate ASO-optimized, guideline-compliant descriptions.
+
+      STRICT RULES for description:
+      - description: 800-4000 chars. First 3 lines = hook + value prop (visible before Read More).
+        Short paragraphs, line breaks, 3-5 bullet features, closing CTA.
+
+      CRITICAL:
+      - You receive a JSON list of `locales_needing_description`. ONLY generate a
+        description for each locale in that list. Do not generate any other fields.
+      - Translate faithfully for each locale's market - not literal word-for-word. Adapt ASO
+        keywords to local search behavior. Respect character limits in the target script
+        (CJK char counts differ from byte counts).
+      - The first paragraph MUST be a strong hook fully visible before the "Read More"
+        cutoff on the App Store product page.
+      - Use short paragraphs separated by line breaks for scannability.
+      - Include 3-5 bullet-style feature lines highlighting key capabilities.
+      - End with a closing call-to-action inviting download or engagement.
+      - Never output URLs (privacyPolicyUrl, supportUrl, marketingUrl, privacyChoicesUrl).
+      - Output STRICT JSON matching the schema - no markdown, no commentary.
+
+  - role: user
+    content: |
+      APP CONTEXT:
+      {{app_context}}
+
+      LOCALES NEEDING DESCRIPTION:
+      {{locales_needing_description}}
+
+      Generate the description for each locale now.
+
+responseFormat: json_schema
+jsonSchema:
+  name: ascDescriptions
+  strict: true
+  schema:
+    type: object
+    additionalProperties: false
+    required: [localizations]
+    properties:
+      localizations:
+        type: object
+        description: "Keyed by Apple locale code (en-US, ja, de-DE, ...)"
+        additionalProperties:
+          type: object
+          additionalProperties: false
+          required: [description]
+          properties:
+            description: { type: string, maxLength: 4000 }

package/action/scripts/app_context_scanner.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""
+Smoke-scan the consumer repo to produce a deterministic <=6KB text blob that
+captures enough product signal for the AI prompt to generate ASO-optimized
+App Store metadata without reading every file.
+
+Sources (in fixed order, each hard-capped):
+  * README.md / readme.md  (2048B)  human pitch
+  * $SCHEME/Info.plist      (512B)  display name + capability keys
+  * Package.swift / Podfile(1024B)  SDK fingerprint (Firebase, RevenueCat, ...)
+  * top 3 *.swift by size  (1536B)  class / view names reveal feature set
+  * Bundle id + scheme      ( 128B)  naming signal
+  * *.entitlements          ( 256B)  capability keys (VPN, iCloud, ...)
+
+Total hard cap: ~6KB. Walk is scoped to $GITHUB_WORKSPACE (or os.getcwd());
+paths resolved against that root are re-checked to prevent traversal.
+Fail-open: any uncaught error -> warning, "<unavailable>" blob, exit 0.
+
+Environment:
+  GITHUB_WORKSPACE  -- repo root (falls back to cwd)
+  BUNDLE_ID         -- app bundle id (from auto_detect or ci.config.yaml)
+  SCHEME            -- Xcode scheme name
+"""
+
+from __future__ import annotations
+
+import os
+import plistlib
+import re
+import sys
+from pathlib import Path
+
+from metadata_constants import warn
+
+
+README_CAP = 2048
+INFO_PLIST_CAP = 512
+DEPS_CAP = 1024
+SWIFT_TOTAL_CAP = 1536
+SWIFT_PER_FILE_CAP = 500
+NAMING_CAP = 128
+ENTITLEMENTS_CAP = 256
+
+
+def _root() -> Path:
+    workspace = os.environ.get("GITHUB_WORKSPACE", "").strip() or os.getcwd()
+    return Path(workspace).resolve()
+
+
+def _safe_path(root: Path, candidate: Path) -> Path | None:
+    """Return resolved candidate if it is inside root, else None.
+
+    Guards against symlinked or traversal-crafted paths reaching outside
+    the workspace. Non-existent paths return None.
+    """
+    try:
+        resolved = candidate.resolve()
+    except OSError:
+        return None
+    try:
+        resolved.relative_to(root)
+    except ValueError:
+        return None
+    if not resolved.exists():
+        return None
+    return resolved
+
+
+def _read_capped(path: Path, cap: int) -> str:
+    try:
+        raw = path.read_bytes()[:cap]
+        return raw.decode("utf-8", errors="replace").strip()
+    except OSError as exc:
+        warn(f"scanner: read failed for {path.name}: {exc!r}")
+        return ""
+
+
+def read_readme(root: Path) -> str:
+    for name in ("README.md", "readme.md", "README.MD", "Readme.md"):
+        p = _safe_path(root, root / name)
+        if p:
+            return _read_capped(p, README_CAP)
+    return ""
+
+
+def _scheme_root(root: Path, scheme: str) -> Path | None:
+    if not scheme:
+        return None
+    for candidate in (root / scheme, root / "Sources" / scheme, root / "Sources"):
+        p = _safe_path(root, candidate)
+        if p and p.is_dir():
+            return p
+    return None
+
+
+def read_info_plist(root: Path, scheme: str) -> str:
+    search_dirs = [d for d in (_scheme_root(root, scheme), root) if d]
+    for base in search_dirs:
+        plist = _safe_path(base, base / "Info.plist")
+        if plist:
+            return _extract_plist_summary(plist)
+    for plist in sorted(root.rglob("Info.plist"))[:5]:
+        safe = _safe_path(root, plist)
+        if safe:
+            summary = _extract_plist_summary(safe)
+            if summary:
+                return summary
+    return ""
+
+
+def _extract_plist_summary(path: Path) -> str:
+    try:
+        with open(path, "rb") as f:
+            data = plistlib.load(f)
+    except (OSError, plistlib.InvalidFileException, ValueError) as exc:
+        warn(f"scanner: plist parse failed for {path.name}: {exc!r}")
+        return ""
+    if not isinstance(data, dict):
+        return ""
+    display = data.get("CFBundleDisplayName") or data.get("CFBundleName") or ""
+    version = data.get("CFBundleShortVersionString") or ""
+    perms = sorted(k for k in data if k.startswith("NS") and "UsageDescription" in k)
+    lines = []
+    if display:
+        lines.append(f"display_name={display}")
+    if version:
+        lines.append(f"version={version}")
+    if perms:
+        lines.append("permissions=" + ",".join(perms))
+    return "\n".join(lines)[:INFO_PLIST_CAP]
+
+
+def read_dependencies(root: Path) -> str:
+    pkg_swift = _safe_path(root, root / "Package.swift")
+    if pkg_swift:
+        return _grep_lines(pkg_swift, r"\.package\s*\(", DEPS_CAP)
+    podfile = _safe_path(root, root / "Podfile")
+    if podfile:
+        return _grep_lines(podfile, r"^\s*pod\s+", DEPS_CAP)
+    return ""
+
+
+def _grep_lines(path: Path, pattern: str, cap: int) -> str:
+    try:
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError as exc:
+        warn(f"scanner: read failed for {path.name}: {exc!r}")
+        return ""
+    regex = re.compile(pattern)
+    matches = [line.strip() for line in text.splitlines() if regex.search(line)]
+    return "\n".join(matches)[:cap]
+
+
+def read_swift_files(root: Path, scheme: str) -> str:
+    base = _scheme_root(root, scheme) or root
+    swift_paths: list[Path] = []
+    for p in base.rglob("*.swift"):
+        safe = _safe_path(root, p)
+        if not safe or "Tests" in safe.parts:
+            continue
+        try:
+            safe.stat()  # confirm readable; sort key below will re-stat
+        except OSError:
+            continue
+        swift_paths.append(safe)
+    swift_paths.sort(key=lambda p: (-p.stat().st_size, p.name))
+    chunks: list[str] = []
+    used = 0
+    for p in swift_paths[:3]:
+        if used >= SWIFT_TOTAL_CAP:
+            break
+        snippet = _read_capped(p, SWIFT_PER_FILE_CAP)
+        if not snippet:
+            continue
+        block = f"--- {p.name} ---\n{snippet}"
+        if used + len(block) > SWIFT_TOTAL_CAP:
+            block = block[: SWIFT_TOTAL_CAP - used]
+        chunks.append(block)
+        used += len(block) + 1
+    return "\n".join(chunks)
+
+
+def read_entitlements(root: Path) -> str:
+    for ent in sorted(root.rglob("*.entitlements"))[:3]:
+        safe = _safe_path(root, ent)
+        if not safe:
+            continue
+        try:
+            with open(safe, "rb") as f:
+                data = plistlib.load(f)
+        except (OSError, plistlib.InvalidFileException, ValueError):
+            continue
+        if isinstance(data, dict) and data:
+            return "\n".join(sorted(data))[:ENTITLEMENTS_CAP]
+    return ""
+
+
+def build_blob() -> str:
+    root = _root()
+    bundle_id = os.environ.get("BUNDLE_ID", "").strip()
+    scheme = os.environ.get("SCHEME", "").strip()
+
+    naming = []
+    if bundle_id:
+        naming.append(f"BUNDLE_ID: {bundle_id}")
+    if scheme:
+        naming.append(f"SCHEME: {scheme}")
+    naming_blob = "\n".join(naming)[:NAMING_CAP]
+
+    sections = [
+        ("===APP CONTEXT===", naming_blob),
+        ("===README===", read_readme(root)),
+        ("===INFO_PLIST===", read_info_plist(root, scheme)),
+        ("===DEPENDENCIES===", read_dependencies(root)),
+        ("===SWIFT_FILES===", read_swift_files(root, scheme)),
+        ("===ENTITLEMENTS===", read_entitlements(root)),
+    ]
+    out_parts: list[str] = []
+    for header, content in sections:
+        out_parts.extend((header, content or "<unavailable>"))
+    out_parts.append("===END===")
+    return "\n".join(out_parts)
+
+
+def main() -> int:
+    try:
+        blob = build_blob()
+    except SystemExit:
+        raise
+    except Exception as exc:
+        warn(f"app context scanner failed (non-fatal): {exc!r}")
+        print("===APP CONTEXT===\n<unavailable>\n===END===")
+        return 0
+    print(blob)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/action/scripts/asc_build_history.py

@@ -0,0 +1,284 @@
+#!/usr/bin/env python3
+# Note: fetch_prerelease_versions (~58 lines) and
+# fetch_builds_prerelease_versions (~59 lines) exceed the 50-line
+# function cap. Pre-existing in the source-of-truth; refactor tracked
+# separately to avoid bundling unrelated edits into round-13 trims.
+"""
+App Store Connect pre-release-version history fetcher.
+
+Split out of asc_version_fetch.py so each module stays focused and under
+the 400-line cap. This module owns:
+
+  - `fetch_prerelease_versions`: paginated list of every TestFlight train
+    versionString (/v1/apps/{id}/preReleaseVersions -> attributes.version).
+    TestFlight trains persist across app updates and feed ASC's upload
+    validator's "previously approved version" floor.
+
+Why NOT /v1/apps/{id}/builds? Two reasons, both learned the hard way:
+
+  1. The app-scoped /builds relationship rejects
+     ``filter[preReleaseVersion.platform]`` with HTTP 400 ("parameter is
+     not permitted on this endpoint"). That filter is only valid on the
+     top-level /v1/builds collection, not the relationship view.
+
+  2. Even if the filter worked, /builds.attributes.version is the INTEGER
+     build number (CFBundleVersion), NOT the marketing versionString.
+     Empirical proof from CI run 24640182161:
+         ASC /builds: scanning 6 builds -> v='3','2','1'
+     Those '3','2','1' are build numbers. Marketing versions on the same
+     app looked like 1.0, 1.0.1, 1.0.4.
+
+So /v1/apps/{id}/builds is unfit for marketing-version discovery.
+/v1/apps/{id}/preReleaseVersions is the authoritative source:
+``attributes.version`` there IS the marketing versionString.
+
+Why no ``filter[platform]`` on the request? CI run 24640348572 proved
+the app-scoped ``/apps/{id}/preReleaseVersions`` relationship endpoint
+rejects ``filter[platform]`` with HTTP 400 ("parameter is not permitted
+on this endpoint"). The filter is only valid on the top-level
+``/preReleaseVersions`` collection. So we fetch unfiltered and filter
+client-side.
+
+Defensive-inclusion rule (CI run 24640430898): records with an EXPLICIT
+non-iOS platform (``MAC_OS``, ``TV_OS``, ``VISION_OS``) are excluded;
+records with iOS OR null/missing platform are INCLUDED. Rationale: the
+409 failure proved ASC can hide preReleaseVersion records that still
+collide with a POST to /appStoreVersions. Better to overbump one patch
+than to miss a hidden collision.
+
+Also in this module (CI run 24640430898): ``fetch_builds_prerelease_versions``
+queries ``/v1/builds?filter[app]={id}&include=preReleaseVersion``,
+cross-references the ``included`` array, and extracts each build's
+preReleaseVersion.attributes.version (the marketing version, not the
+build number). This reveals preReleaseVersions that the direct
+/preReleaseVersions query might miss (pagination truncation or state
+filtering). The build's own ``attributes.version`` is the INTEGER build
+number (CFBundleVersion) and is NOT used.
+
+Why the TOP-LEVEL ``/v1/builds`` collection (not ``/v1/apps/{id}/builds``)?
+CI run 24640675162 proved the app-scoped relationship endpoint rejects
+``include=preReleaseVersion`` with HTTP 400 PARAMETER_ERROR.ILLEGAL
+(`"The parameter 'include' can not be used with this request"`). The
+top-level ``/v1/builds`` collection DOES accept both ``filter[app]``
+and ``include``, so we query that instead and scope by ``filter[app]``.
+
+(``next_build_number.py`` still uses /builds -- but it needs build
+numbers, not marketing versions, so that usage is correct.)
+"""
+
+from __future__ import annotations
+
+import sys
+
+from asc_common import request
+
+
+def _iter_pages(path: str, token: str, params: dict):
+    """Generator over `.data` lists across paginated ASC responses.
+
+    Follows `links.next` verbatim (stripping the `/v1` prefix so we stay
+    on the retrying client). Yields each record; callers decide what to
+    extract and how to log.
+    """
+    resp = request("GET", path, token, params=params)
+    while True:
+        data = resp.json()
+        for item in data.get("data", []):
+            yield item
+        next_url = ((data.get("links") or {}).get("next")) or ""
+        if not next_url:
+            return
+        next_path = next_url.split("/v1", 1)[-1] if "/v1" in next_url else next_url
+        resp = request("GET", next_path, token)
+
+
+_EXPLICIT_NON_IOS_PLATFORMS = {"MAC_OS", "TV_OS", "VISION_OS"}
+
+
+def _platform_is_counted(platform: str | None) -> bool:
+    """Defensive inclusion rule: include iOS and null/missing platform;
+    exclude only explicit known-wrong platforms. Keeps hidden records
+    from slipping past the floor (CI run 24640430898)."""
+    if platform in _EXPLICIT_NON_IOS_PLATFORMS:
+        return False
+    return True
+
+
+def fetch_prerelease_versions(app_id: str, token: str) -> list[str]:
+    """Return every TestFlight train's versionString for the app.
+
+    Paginates through links.next so mature apps with >200 trains are not
+    truncated. Filters client-side -- the app-scoped
+    ``/apps/{id}/preReleaseVersions`` relationship endpoint rejects
+    ``filter[platform]`` with HTTP 400 (CI run 24640348572), so we drop
+    the server-side filter and evaluate ``attributes.platform`` on each
+    returned record instead.
+
+    Defensive inclusion (CI run 24640430898): iOS records AND records
+    with null/missing platform are INCLUDED; only explicit MAC_OS /
+    TV_OS / VISION_OS are excluded. Records with missing/null version
+    are skipped regardless.
+    """
+    path = f"/apps/{app_id}/preReleaseVersions"
+    params = {"limit": 200}
+    out: list[str] = []
+    skipped = 0
+    for item in _iter_pages(path, token, params):
+        attrs = item.get("attributes") or {}
+        version = attrs.get("version")
+        platform = attrs.get("platform")
+        record_id = item.get("id", "")
+        if not version:
+            print(
+                f"[prerelease-history] skip id={record_id} "
+                f"platform={platform or '<null>'} reason=missing-version",
+                file=sys.stderr,
+            )
+            skipped += 1
+            continue
+        if not _platform_is_counted(platform):
+            print(
+                f"[prerelease-history] skip id={record_id} version={version} "
+                f"platform={platform or '<null>'} reason=not-ios",
+                file=sys.stderr,
+            )
+            skipped += 1
+            continue
+        out.append(version)
+        if platform == "IOS":
+            log_msg = (
+                f"[prerelease-history] version={version} "
+                f"platform=IOS id={record_id}"
+            )
+        else:
+            log_msg = (
+                f"[prerelease-history] version={version} "
+                f"platform=<null> id={record_id} "
+                f"reason=included-defensively"
+            )
+        print(log_msg, file=sys.stderr)
+    print(
+        f"[prerelease-history] done: trains={len(out)} skipped={skipped}",
+        file=sys.stderr,
+    )
+    return out
+
+
+def fetch_builds_prerelease_versions(app_id: str, token: str) -> list[str]:
+    """Return every build's referenced preReleaseVersion marketing version.
+
+    Queries the TOP-LEVEL
+    ``/v1/builds?filter[app]={id}&include=preReleaseVersion`` collection
+    and cross-references the ``included`` array to resolve each build's
+    ``relationships.preReleaseVersion.data.id`` -> the corresponding
+    ``included`` record's ``attributes.version`` (marketing version,
+    NOT the build number).
+
+    The app-scoped relationship endpoint ``/v1/apps/{id}/builds`` rejects
+    the ``include`` parameter with HTTP 400 PARAMETER_ERROR.ILLEGAL
+    (`"The parameter 'include' can not be used with this request"`,
+    CI run 24640675162). The top-level collection accepts both
+    ``filter[app]`` and ``include``, so we query that and scope by app.
+
+    Paginates through links.next. Same defensive platform rule as
+    fetch_prerelease_versions: iOS / null included, explicit non-iOS
+    excluded. Each cross-reference is logged.
+
+    Rationale: CI run 24640430898 exposed a hidden preReleaseVersion
+    that the direct /preReleaseVersions query did not surface, yet a
+    POST to /appStoreVersions for that version returned 409. The
+    builds->preReleaseVersion path is a second, independent view of
+    those same records and catches ones missed by the direct query.
+    """
+    path = "/builds"
+    params = {
+        "filter[app]": app_id,
+        "include": "preReleaseVersion",
+        "limit": 200,
+    }
+    out: list[str] = []
+    counters = {"builds_scanned": 0, "skipped": 0}
+
+    resp = request("GET", path, token, params=params)
+    while True:
+        data = resp.json()
+        included_by_id = _index_included(data.get("included") or [])
+        for build in data.get("data", []):
+            counters["builds_scanned"] += 1
+            version = _extract_build_prerelease_version(
+                build, included_by_id, counters,
+            )
+            if version is not None:
+                out.append(version)
+
+        next_url = ((data.get("links") or {}).get("next")) or ""
+        if not next_url:
+            break
+        next_path = next_url.split("/v1", 1)[-1] if "/v1" in next_url else next_url
+        resp = request("GET", next_path, token)
+
+    print(
+        f"[builds-prerelease] done: builds={counters['builds_scanned']} "
+        f"versions={len(out)} skipped={counters['skipped']}",
+        file=sys.stderr,
+    )
+    return out
+
+
+def _extract_build_prerelease_version(
+    build: dict, included_by_id: dict[str, dict], counters: dict,
+) -> str | None:
+    """Return the build's referenced preReleaseVersion marketing version
+    if it passes the defensive platform filter; else None. ``counters``
+    is mutated to track skips for the done-line summary."""
+    rel_id = _prerelease_ref_id(build)
+    if not rel_id:
+        return None
+    ref = included_by_id.get(rel_id)
+    if ref is None:
+        return None
+    attrs = ref.get("attributes") or {}
+    version = attrs.get("version")
+    platform = attrs.get("platform")
+    if not version:
+        counters["skipped"] += 1
+        return None
+    if not _platform_is_counted(platform):
+        print(
+            f"[builds-prerelease] skip build={build.get('id', '')} "
+            f"prerelease_id={rel_id} version={version} "
+            f"platform={platform or '<null>'} reason=not-ios",
+            file=sys.stderr,
+        )
+        counters["skipped"] += 1
+        return None
+    print(
+        f"[builds-prerelease] build={build.get('id', '')} "
+        f"prerelease_id={rel_id} version={version} "
+        f"platform={platform or '<null>'}",
+        file=sys.stderr,
+    )
+    return version
+
+
+def _index_included(included: list[dict]) -> dict[str, dict]:
+    """Build {id: record} map restricted to preReleaseVersions for O(1)
+    cross-reference from a build's relationships.preReleaseVersion.data.id."""
+    out: dict[str, dict] = {}
+    for rec in included:
+        if rec.get("type") != "preReleaseVersions":
+            continue
+        rid = rec.get("id")
+        if rid:
+            out[rid] = rec
+    return out
+
+
+def _prerelease_ref_id(build: dict) -> str | None:
+    """Return the preReleaseVersion id referenced by a build, or None
+    if the relationship is absent/empty."""
+    rels = build.get("relationships") or {}
+    pre = rels.get("preReleaseVersion") or {}
+    data = pre.get("data") or {}
+    rid = data.get("id")
+    return rid if rid else None