release_gates.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tools/release_gates.py
 
"""
Release-time version gates for the OC Chat single-version system.
 
Purpose
-------
Two mechanical, re-runnable gates (Plan 143g-code S5; addendum §"Acceptance
tests" — orchestrator release-time gates). They run at the ``v0.8.0`` cut (and
every later release), NOT in the branch worktree suite — no ``v0.8.0`` tag
exists pre-release, so the *release-mode* run only ever goes green on the exact
annotated release commit. This module ships the tooling + its unit tests; the
real invocation is the orchestrator's, per the addendum's bundle transaction.
 
Responsibilities
----------------
- :func:`consistency_gate` / :func:`code_equality_gate` — the two pure gate
  predicates over already-parsed inputs (fixture-testable).
- :func:`read_manifest_version` / :func:`read_view_headers` /
  :func:`read_configured_fallbacks` — isolated I/O: direct source/render reads.
- :func:`parse_view_header` — the per-view-STRICT header grammar.
- :func:`is_rejected_fallback` — the reject-on-EITHER fallback predicate.
- :func:`run_gates` / :func:`main` — mode dispatch + typed process exits.
 
The two gates
-------------
- **Consistency gate** (committed axis): the Release-tag helper value ==
  manifest ``extensions.current_version`` == the four rendered ``**Version:**``
  headers. Needs the annotated tag, so it runs in ``--mode release`` only.
- **Code-equality gate** (live axis vs committed): installed package release
  core == :func:`resolve_version` == manifest ``current_version`` == the
  headers.
 
Modes
-----
- ``--mode release`` — ONE invocation runs BOTH gates, EXACT equality (no
  ``.devN`` / local suffix tolerated), required on the exact annotated
  ``v0.8.0`` release commit. Any consulted live version equal to EITHER a
  configured ``fallback_version`` (read from the two pyprojects) OR the pinned
  sentinel ``0.0.0.dev0`` is rejected — reject-on-EITHER, never a conjunction.
- ``--mode dev-smoke`` — tolerates ``.devN+ghash`` on the live axis (compares
  release cores); runs the code-equality + header-consistency checks but NOT
  the tag-consistency check (no release tag exists in dogfood). Its report
  STATES it is NOT a release authorization.
 
The gate never imports ``registry/render/**``: the manifest read is a DIRECT
source read of ``oc_chat/roadmap/source/manifest.md`` frontmatter, and the view
headers are parsed straight from the rendered files.
 
Header grammar (per-view STRICT — addendum §"The header fix" V13.3 table):
``**Version:** {version}`` on all four views; ``· Round {N}`` REQUIRED and
value-checked on ``ROADMAP-CHANGELOG.md`` only, FORBIDDEN on the three bare
views (``ROADMAP.md`` / ``ROADMAP-EXTENDED.md`` / product ``CHANGELOG.md``).
 
Exit codes
----------
- 0 — all requested gates passed.
- 1 — a gate violation (drift / inequality / rejected fallback).
- 2 — usage or configuration error (bad args, missing/malformed inputs).
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 — lifecycle events (gate pass/fail)
    L3 — semantic details (per-axis values)
    L4 — deep tracing
 
Contracts
---------
- Gate functions are pure over their parsed inputs (fixture-testable); I/O is
  isolated in the ``read_*`` / ``load_*`` helpers.
- Fail-closed with diagnostics NAMING the disagreeing axis.
 
Dependencies
------------
- packaging (packaging.version.Version — declared in both pyprojects, S1b)
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.core.release_tag (lazy; resolve_release_tag and release_tag_core - the annotated release tag and its prefix-aware version core)
- oc_chat.core._version (lazy; resolve_version - the live version for the code-equality gate)
- yaml (lazy; PyYAML safe_load of the roadmap manifest frontmatter)
"""
from __future__ import annotations
 
import argparse
import re
import sys
from dataclasses import dataclass, field
from pathlib import Path
from typing import Optional
 
from packaging.version import InvalidVersion, Version
 
from oc_diagnostics import _dbg
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
EXIT_OK = 0
EXIT_GATE_VIOLATION = 1
EXIT_USAGE = 2
 
# The pinned degraded sentinel shared by both pyprojects' fallback_version
# (Plan 143g-code S1). Reject-on-EITHER this OR any configured fallback value.
PINNED_FALLBACK_SENTINEL = "0.0.0.dev0"
 
# Middle dot separating version and round in the roadmap-changelog header.
_MIDDLE_DOT = "·"
 
_REPO_ROOT = Path(__file__).resolve().parent.parent
DEFAULT_MANIFEST = _REPO_ROOT / "oc_chat" / "roadmap" / "source" / "manifest.md"
DEFAULT_PYPROJECTS = (
    _REPO_ROOT / "pyproject.toml",
    _REPO_ROOT / "oc_chat" / "pyproject.toml",
)
 
 
@dataclass(frozen=True)
class ViewSpec:
    """One rendered living-set view + whether its header carries ``· Round N``."""
 
    key: str
    rel_path: str
    requires_round: bool
 
 
# The four rendered views (addendum §S5 render-side inputs; per-view Round policy).
_ROADMAP_DIR = "oc_chat/roadmap"
VIEWS: tuple[ViewSpec, ...] = (
    ViewSpec("roadmap", f"{_ROADMAP_DIR}/ROADMAP.md", False),
    ViewSpec("roadmap_extended", f"{_ROADMAP_DIR}/ROADMAP-EXTENDED.md", False),
    ViewSpec("roadmap_changelog", f"{_ROADMAP_DIR}/ROADMAP-CHANGELOG.md", True),
    ViewSpec("product_changelog", "CHANGELOG.md", False),
)
 
# `**Version:** X` optionally followed by ` · Round N`. First match wins.
_HEADER_RE = re.compile(
    r"^\*\*Version:\*\*[ \t]+(?P<version>\S+)"
    r"(?:[ \t]+" + re.escape(_MIDDLE_DOT) + r"[ \t]+Round[ \t]+(?P<round>\d+))?"
    r"[ \t]*$",
    re.MULTILINE,
)
 
 
class GateConfigError(Exception):
    """A usage / configuration problem → exit 2 (not a gate violation)."""
 
 
@dataclass
class ParsedHeader:
    version: str
    round_no: Optional[int]
 
 
@dataclass
class GateOutcome:
    """Result of one gate: pass/fail + the human-readable failure reasons."""
 
    name: str
    passed: bool
    failures: list[str] = field(default_factory=list)
 
    def fail(self, reason: str) -> None:
        self.passed = False
        self.failures.append(reason)
 
 
# ---------------------------------------------------------------------------
# I/O — direct source / render reads (never imports registry/render/**)
# ---------------------------------------------------------------------------
 
 
def _read_frontmatter(path: Path) -> dict:
    """Return the YAML frontmatter of a markdown source record as a dict."""
    try:
        import yaml  # PyYAML — the house source loader (canonical.py) uses it too
    except ImportError as e:  # pragma: no cover — PyYAML present in this env
        raise GateConfigError(f"PyYAML required to read {path}: {e}") from e
    try:
        text = path.read_text(encoding="utf-8")
    except OSError as e:
        raise GateConfigError(f"cannot read {path}: {e}") from e
    if not text.startswith("---"):
        raise GateConfigError(f"{path}: no YAML frontmatter fence")
    parts = text.split("---", 2)
    if len(parts) < 3:
        raise GateConfigError(f"{path}: unterminated frontmatter fence")
    data = yaml.safe_load(parts[1]) or {}
    if not isinstance(data, dict):
        raise GateConfigError(f"{path}: frontmatter is not a mapping")
    return data
 
 
def read_manifest_version(manifest_path: Path) -> str:
    """Return manifest ``extensions.current_version`` (direct source read)."""
    data = _read_frontmatter(manifest_path)
    ext = data.get("extensions")
    if not isinstance(ext, dict) or "current_version" not in ext:
        raise GateConfigError(
            f"{manifest_path}: extensions.current_version missing "
            "(143g authors it at the cutover)"
        )
    return str(ext["current_version"])
 
 
def read_configured_fallbacks(pyproject_paths: tuple[Path, ...]) -> set[str]:
    """Read every ``[tool.setuptools_scm].fallback_version`` from the pyprojects."""
    try:
        import tomllib  # Python >= 3.11
    except ImportError as e:  # pragma: no cover — repo requires >= 3.10, CI covers 3.11+
        raise GateConfigError(f"tomllib required (Python >= 3.11): {e}") from e
    fallbacks: set[str] = set()
    for p in pyproject_paths:
        try:
            data = tomllib.loads(p.read_text(encoding="utf-8"))
        except (OSError, tomllib.TOMLDecodeError) as e:
            raise GateConfigError(f"cannot parse {p}: {e}") from e
        fb = data.get("tool", {}).get("setuptools_scm", {}).get("fallback_version")
        if fb:
            fallbacks.add(str(fb))
    return fallbacks
 
 
def parse_view_header(text: str, view: ViewSpec) -> ParsedHeader:
    """Parse the first ``**Version:**`` header of a view, per-view-STRICT.
 
    Enforces the V13.3 per-view grammar: ``· Round N`` is REQUIRED on the
    roadmap-changelog view and FORBIDDEN on the three bare views.
    """
    m = _HEADER_RE.search(text)
    if m is None:
        raise GateConfigError(f"{view.rel_path}: no '**Version:**' header found")
    round_no = int(m.group("round")) if m.group("round") is not None else None
    if view.requires_round and round_no is None:
        raise GateConfigError(
            f"{view.rel_path}: header MUST carry '{_MIDDLE_DOT} Round N' (missing)"
        )
    if not view.requires_round and round_no is not None:
        raise GateConfigError(
            f"{view.rel_path}: header MUST NOT carry '{_MIDDLE_DOT} Round N' "
            f"(found Round {round_no})"
        )
    return ParsedHeader(version=m.group("version"), round_no=round_no)
 
 
def read_view_headers(view_root: Path) -> dict[str, ParsedHeader]:
    """Parse the four rendered view headers under ``view_root`` (the repo root)."""
    headers: dict[str, ParsedHeader] = {}
    for view in VIEWS:
        path = view_root / view.rel_path
        try:
            text = path.read_text(encoding="utf-8")
        except OSError as e:
            raise GateConfigError(f"cannot read view {view.rel_path}: {e}") from e
        headers[view.key] = parse_view_header(text, view)
    return headers
 
 
# ---------------------------------------------------------------------------
# Pure predicates + gates (fixture-testable — no I/O)
# ---------------------------------------------------------------------------
 
 
def is_rejected_fallback(version: str, configured_fallbacks: set[str]) -> bool:
    """Reject-on-EITHER: the pinned sentinel OR any configured fallback value.
 
    Never a conjunction — an ``and`` implementation stays green on the pinned
    untagged-archive state (where configured == sentinel and both fire together)
    while silently dropping the value-independent belt (R05 both reviewers).
    """
    return version == PINNED_FALLBACK_SENTINEL or version in configured_fallbacks
 
 
def _release_core(version: str) -> tuple[int, ...]:
    try:
        return Version(version).release
    except InvalidVersion as e:
        raise GateConfigError(f"not a PEP-440 version: {version!r} ({e})") from e
 
 
def _is_clean_release(version: str) -> bool:
    """True iff ``version`` is a final/post release (no dev / pre / local)."""
    try:
        v = Version(version)
    except InvalidVersion:
        return False
    return v.pre is None and v.dev is None and v.local is None
 
 
def consistency_gate(
    *,
    release_tag: str,
    manifest_version: str,
    headers: dict[str, ParsedHeader],
    configured_fallbacks: set[str],
) -> GateOutcome:
    """Release-tag value == manifest current_version == the four headers (exact)."""
    out = GateOutcome(name="consistency", passed=True)
    # Plan 151 T2 / AC 18a: PREFIX-AWARE strip — the release-tag namespace is
    # `oc_chat-v*` post-migration; the strip is single-sourced from
    # oc_chat.core.release_tag (which reads the prefix from the scm config).
    # The old bare `[1:]` v-strip would compare 'oc_chat-v0.8.0' to '0.8.0'.
    from oc_chat.core.release_tag import release_tag_core
 
    tag_core = release_tag_core(release_tag)
    if not _is_clean_release(manifest_version):
        out.fail(f"manifest current_version is not a clean release: {manifest_version!r}")
    if is_rejected_fallback(manifest_version, configured_fallbacks):
        out.fail(f"manifest current_version is a rejected fallback: {manifest_version!r}")
    if tag_core != manifest_version:
        out.fail(
            f"release tag {release_tag!r} (core {tag_core!r}) != "
            f"manifest current_version {manifest_version!r}"
        )
    for view in VIEWS:
        hv = headers[view.key].version
        if hv != manifest_version:
            out.fail(
                f"{view.rel_path} header version {hv!r} != "
                f"manifest current_version {manifest_version!r}"
            )
    return out
 
 
def code_equality_gate(
    *,
    installed_version: str,
    resolved_version: str,
    manifest_version: str,
    headers: dict[str, ParsedHeader],
    configured_fallbacks: set[str],
    exact: bool,
) -> GateOutcome:
    """Installed pkg == resolve_version() == manifest == headers.
 
    ``exact`` (release mode): full-string equality, no suffix tolerated, and the
    live versions must not be a rejected fallback. Otherwise (dev-smoke): compare
    release cores only, tolerating ``.devN+local`` on the live axis.
    """
    out = GateOutcome(name="code-equality", passed=True)
 
    for label, val in (("installed package", installed_version), ("resolve_version()", resolved_version)):
        if is_rejected_fallback(val, configured_fallbacks):
            out.fail(f"{label} version is a rejected fallback: {val!r}")
 
    header_versions = {headers[v.key].version for v in VIEWS}
    if len(header_versions) != 1:
        out.fail(f"rendered headers disagree: {sorted(header_versions)}")
 
    if exact:
        axes = {
            "installed package": installed_version,
            "resolve_version()": resolved_version,
            "manifest current_version": manifest_version,
            **{f"{v.rel_path} header": headers[v.key].version for v in VIEWS},
        }
        distinct = set(axes.values())
        if distinct != {manifest_version}:
            out.fail(
                "exact equality failed across axes: "
                + ", ".join(f"{k}={val!r}" for k, val in axes.items())
            )
        if not _is_clean_release(manifest_version):
            out.fail(f"manifest current_version is not a clean release: {manifest_version!r}")
    else:
        core = _release_core(manifest_version)
        for label, val in (
            ("installed package", installed_version),
            ("resolve_version()", resolved_version),
            ("manifest current_version", manifest_version),
            *[(f"{v.rel_path} header", headers[v.key].version) for v in VIEWS],
        ):
            if _release_core(val) != core:
                out.fail(
                    f"{label} release core {_release_core(val)} != manifest core {core}"
                )
    return out
 
 
# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------
 
 
def _emit(outcome: GateOutcome) -> None:
    func = "_emit"
    status = "PASS" if outcome.passed else "FAIL"
    print(f"[{status}] {outcome.name} gate")
    for reason in outcome.failures:
        print(f"    - {reason}")
    _dbg("OC_CHAT.MAIN", func, f"{outcome.name}: {status}", 2)
 
 
def run_gates(args: argparse.Namespace) -> int:
    """Load inputs, run the mode's gates, return the process exit code."""
    func = "run_gates"
    view_root = Path(args.repo_root)
    manifest_path = Path(args.manifest)
    pyprojects = tuple(Path(p) for p in args.pyproject)
 
    try:
        manifest_version = read_manifest_version(manifest_path)
        headers = read_view_headers(view_root)
        configured_fallbacks = read_configured_fallbacks(pyprojects)
        installed_version = _installed_version()
        from oc_chat.core._version import resolve_version
        resolved_version = resolve_version()
    except GateConfigError as e:
        print(f"[ERROR] {e}", file=sys.stderr)
        _dbg("OC_CHAT.MAIN", func, f"VALIDATION_ERROR: {e}", 3)
        return EXIT_USAGE
 
    outcomes: list[GateOutcome] = []
 
    if args.mode == "release":
        try:
            from oc_chat.core.release_tag import ReleaseTagError, resolve_release_tag
            release_tag = resolve_release_tag(view_root, commit=args.commit)
        except Exception as e:  # ReleaseTagError or unexpected — fail-closed as a violation
            print(f"[FAIL] consistency gate\n    - release-tag resolution failed: {e}")
            _dbg("OC_CHAT.MAIN", func, f"release-tag failure: {e}", 2, override=True)
            return EXIT_GATE_VIOLATION
        outcomes.append(
            consistency_gate(
                release_tag=release_tag,
                manifest_version=manifest_version,
                headers=headers,
                configured_fallbacks=configured_fallbacks,
            )
        )
        outcomes.append(
            code_equality_gate(
                installed_version=installed_version,
                resolved_version=resolved_version,
                manifest_version=manifest_version,
                headers=headers,
                configured_fallbacks=configured_fallbacks,
                exact=True,
            )
        )
    else:  # dev-smoke
        outcomes.append(
            code_equality_gate(
                installed_version=installed_version,
                resolved_version=resolved_version,
                manifest_version=manifest_version,
                headers=headers,
                configured_fallbacks=configured_fallbacks,
                exact=False,
            )
        )
 
    for outcome in outcomes:
        _emit(outcome)
 
    if args.mode == "dev-smoke":
        print("NOTE: --mode dev-smoke is NOT a release authorization "
              "(tolerates .devN on the live axis; no tag-consistency check).")
 
    return EXIT_OK if all(o.passed for o in outcomes) else EXIT_GATE_VIOLATION
 
 
def _installed_version() -> str:
    """The installed package version resolve_version() consults first."""
    try:
        from importlib.metadata import PackageNotFoundError
        from importlib.metadata import version as _pkg_version
    except ImportError as e:  # pragma: no cover
        raise GateConfigError(f"importlib.metadata unavailable: {e}") from e
    for dist in ("oc_chat", "oc_chat-workspace"):
        try:
            return _pkg_version(dist)
        except PackageNotFoundError:
            continue
    raise GateConfigError(
        "neither oc_chat nor oc_chat-workspace is installed; "
        "run the release procedure's editable install first"
    )
 
 
def build_parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(
        prog="release_gates.py",
        description="OC Chat release-time version gates (Plan 143g-code S5).",
    )
    p.add_argument("--mode", required=True, choices=("release", "dev-smoke"))
    p.add_argument("--repo-root", default=str(_REPO_ROOT),
                   help="repo root holding the rendered views (default: this checkout)")
    p.add_argument("--manifest", default=str(DEFAULT_MANIFEST),
                   help="path to roadmap source manifest.md")
    p.add_argument("--pyproject", action="append", default=None,
                   help="pyproject.toml to read fallback_version from (repeatable)")
    p.add_argument("--commit", default="HEAD",
                   help="release commit for the tag-consistency check (release mode)")
    return p
 
 
def main(argv: Optional[list[str]] = None) -> int:
    parser = build_parser()
    try:
        args = parser.parse_args(argv)
    except SystemExit:
        # argparse already printed usage; normalize to our usage exit code.
        return EXIT_USAGE
    if args.pyproject is None:
        args.pyproject = [str(p) for p in DEFAULT_PYPROJECTS]
    return run_gates(args)
 
 
if __name__ == "__main__":
    raise SystemExit(main())