Release

#!/usr/bin/env python3
"""Config-driven release engine (stdlib only).

Pure functions (parse/bump/changelog/surface-gate/config/plan) are unit-tested
in test_release.py. The CLI wraps them with side effects (reading/writing files,
git). See ../SKILL.md for the full /release orchestration and teaching layer.
"""
from __future__ import annotations

import argparse
import json
import re
from dataclasses import dataclass
from pathlib import Path


class ReleaseError(Exception):
    """User-facing, recoverable error (printed; CLI exits non-zero)."""


@dataclass(frozen=True)
class Version:
    major: int
    minor: int
    patch: int

    def __str__(self) -> str:
        return f"{self.major}.{self.minor}.{self.patch}"


# --- SemVer ----------------------------------------------------------------

_SEMVER = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")


def parse_version(s: str) -> Version:
    m = _SEMVER.match(s.strip())
    if not m:
        raise ReleaseError(f"not a SemVer x.y.z: {s!r}")
    return Version(int(m[1]), int(m[2]), int(m[3]))


def bump(v: Version, kind: str) -> Version:
    if kind == "major":
        return Version(v.major + 1, 0, 0)
    if kind == "minor":
        return Version(v.major, v.minor + 1, 0)
    if kind == "patch":
        return Version(v.major, v.minor, v.patch + 1)
    raise ReleaseError(f"bump kind must be major|minor|patch, got {kind!r}")


# --- version files (JSON pointer / TOML key) -------------------------------

try:  # read-only; present on 3.11+
    import tomllib
except ModuleNotFoundError:  # pragma: no cover
    tomllib = None


def read_version_file(path, kind: str, *, pointer=None, key=None) -> str:
    text = Path(path).read_text()
    if kind == "json":
        node = json.loads(text)
        for part in [p for p in (pointer or "").split("/") if p]:
            if not isinstance(node, dict) or part not in node:
                raise ReleaseError(f"JSON pointer {pointer} not found in {path}")
            node = node[part]
        return str(node)
    if kind == "toml":
        sect, name = key.split(".", 1)
        if tomllib:
            data = tomllib.loads(text)
            try:
                return str(data[sect][name])
            except KeyError:
                raise ReleaseError(f"no {key} in {path}")
        m = re.search(
            rf'(?ms)^\[{re.escape(sect)}\].*?^{re.escape(name)}\s*=\s*"([^"]+)"', text
        )
        if not m:
            raise ReleaseError(f"no {key} in {path}")
        return m[1]
    raise ReleaseError(f"unknown version-file kind {kind!r}")


def write_version_file(path, kind: str, new: str, *, pointer=None, key=None) -> None:
    # Match on key AND the *current* value, and require exactly one occurrence in
    # the whole file. This refuses to guess (and corrupt) when a same-named key
    # exists elsewhere — it errors loudly instead. Preserves file formatting.
    path = Path(path)
    old = read_version_file(path, kind, pointer=pointer, key=key)
    if old == new:
        return  # idempotent
    text = path.read_text()
    if kind == "json":
        leaf = [p for p in (pointer or "").split("/") if p][-1]
        pat = rf'("{re.escape(leaf)}"\s*:\s*)"{re.escape(old)}"'
        new_text, n = re.subn(pat, rf'\g<1>"{new}"', text)
        if n != 1:
            raise ReleaseError(
                f'expected exactly one "{leaf}": "{old}" in {path}, found {n} '
                f"(ambiguous — refusing to rewrite)"
            )
        path.write_text(new_text)
        return
    if kind == "toml":
        sect, name = key.split(".", 1)
        # `[^\[]*?` refuses to cross into another [section] header, so the match
        # is structurally confined to the target section.
        pat = rf'(?ms)(^\[{re.escape(sect)}\][^\[]*?^{re.escape(name)}\s*=\s*)"{re.escape(old)}"'
        new_text, n = re.subn(pat, rf'\g<1>"{new}"', text, count=1)
        if n != 1:
            raise ReleaseError(f"could not rewrite {key}={old!r} in {path} (found {n})")
        path.write_text(new_text)
        return
    raise ReleaseError(f"unknown version-file kind {kind!r}")


# --- changelog -------------------------------------------------------------

_CC = re.compile(r"^(?P<type>\w+)(?:\([^)]*\))?(?P<bang>!)?:\s*(?P<desc>.+)$")
_BUCKETS = {"feat": "Added", "fix": "Fixed", "perf": "Changed", "refactor": "Changed"}
_SKIP = {"chore", "docs", "test", "ci", "style", "build"}


def draft_changelog(version: str, date: str, commit_subjects) -> str:
    groups: dict[str, list[str]] = {}
    for s in commit_subjects:
        m = _CC.match(s.strip())
        if not m:
            continue
        t = m["type"]
        if t in _SKIP and not m["bang"]:
            continue
        section = "Changed" if m["bang"] else _BUCKETS.get(t, "Changed")
        groups.setdefault(section, []).append(m["desc"].strip())
    out = [f"## [{version}] - {date}", ""]
    for section in ("Added", "Changed", "Fixed"):
        items = groups.get(section)
        if not items:
            continue
        out.append(f"### {section}")
        out += [f"- {i}" for i in items]
        out.append("")
    return "\n".join(out).rstrip() + "\n"


# --- surface-tier gate -----------------------------------------------------

_ORDER = {"patch": 0, "minor": 1, "major": 2}


def required_bump(surfaces_changed) -> str:
    req = "patch"
    for s in surfaces_changed:
        if s.get("breaking") and s.get("tier") == "stable":
            return "major"
        # any declared change to a surface is at least a minor
        if _ORDER[req] < _ORDER["minor"]:
            req = "minor"
    return req


def enforce_bump(requested: str, required: str) -> None:
    if _ORDER[requested] < _ORDER[required]:
        raise ReleaseError(
            f"requested '{requested}' but a {required} bump is required "
            f"(a stable surface changed incompatibly). See COMPATIBILITY.md."
        )


# --- config + plan ---------------------------------------------------------

_TIERS = {"experimental", "preview", "stable"}


def load_config(path) -> dict:
    cfg = json.loads(Path(path).read_text())
    for req in ("versionFiles", "gate", "compatibility", "surfaces", "tag"):
        if req not in cfg:
            raise ReleaseError(f"release.config.json missing '{req}'")
    if not cfg["versionFiles"]:
        raise ReleaseError("versionFiles must be non-empty")
    for vf in cfg["versionFiles"]:
        if "path" not in vf or "kind" not in vf:
            raise ReleaseError("each versionFile needs 'path' and 'kind'")
        if vf["kind"] not in ("json", "toml"):
            raise ReleaseError(f"versionFile kind must be json|toml, got {vf['kind']!r}")
        if vf["kind"] == "json" and not vf.get("pointer"):
            raise ReleaseError(f"versionFile {vf['path']!r}: json kind requires 'pointer'")
        if vf["kind"] == "toml" and not vf.get("key"):
            raise ReleaseError(f"versionFile {vf['path']!r}: toml kind requires 'key'")
    for s in cfg["surfaces"]:
        if s.get("tier") not in _TIERS:
            raise ReleaseError(
                f"surface {s.get('id')!r}: tier must be one of {sorted(_TIERS)}"
            )
    return cfg


def build_plan(cfg: dict, current: str, kind: str) -> dict:
    new = str(bump(parse_version(current), kind))
    prefix = cfg.get("tag", {}).get("prefix", "v")
    return {
        "new_version": new,
        "tag": f"{prefix}{new}",
        "files": [vf["path"] for vf in cfg["versionFiles"]],
    }


# --- CLI -------------------------------------------------------------------


def _current_version(cfg: dict) -> str:
    vf = cfg["versionFiles"][0]
    return read_version_file(
        Path(vf["path"]), vf["kind"], pointer=vf.get("pointer"), key=vf.get("key")
    )


def _assert_versions_agree(cfg: dict) -> str:
    seen = {}
    for vf in cfg["versionFiles"]:
        seen[vf["path"]] = read_version_file(
            Path(vf["path"]), vf["kind"], pointer=vf.get("pointer"), key=vf.get("key")
        )
    distinct = set(seen.values())
    if len(distinct) != 1:
        raise ReleaseError(f"version files disagree before bump: {seen}")
    return distinct.pop()


def _cmd_plan(args):
    cfg = load_config(Path(args.config))
    plan = build_plan(cfg, _current_version(cfg), args.kind)
    print(json.dumps(plan, indent=2))


def _cmd_bump(args):
    """Write the new version into every versionFile (no git side effects)."""
    cfg = load_config(Path(args.config))
    cur = _assert_versions_agree(cfg)
    new = str(bump(parse_version(cur), args.kind))
    for vf in cfg["versionFiles"]:
        write_version_file(
            Path(vf["path"]), vf["kind"], new, pointer=vf.get("pointer"), key=vf.get("key")
        )
    print(f"bumped {cur} -> {new} across {len(cfg['versionFiles'])} files")


def main(argv=None):
    ap = argparse.ArgumentParser(prog="release")
    ap.add_argument("--config", default="release.config.json")
    sub = ap.add_subparsers(dest="cmd", required=True)

    p = sub.add_parser("plan", help="show the planned version/tag (no mutation)")
    p.add_argument("kind", choices=["patch", "minor", "major"])
    p.set_defaults(func=_cmd_plan)

    b = sub.add_parser("bump", help="write the new version into the version files")
    b.add_argument("kind", choices=["patch", "minor", "major"])
    b.set_defaults(func=_cmd_bump)

    args = ap.parse_args(argv)
    try:
        args.func(args)
    except ReleaseError as e:
        print(f"error: {e}")
        raise SystemExit(2)


if __name__ == "__main__":
    main()

"""Unit tests for the release engine. Stdlib unittest, no external deps.

Run: python3 -m unittest test_release -v
"""
import json
import tempfile
import unittest
from pathlib import Path

from release import (
    Version,
    parse_version,
    bump,
    read_version_file,
    write_version_file,
    draft_changelog,
    required_bump,
    enforce_bump,
    load_config,
    build_plan,
    ReleaseError,
)


class TestVersion(unittest.TestCase):
    def test_parse(self):
        self.assertEqual(parse_version("1.2.3"), Version(1, 2, 3))

    def test_parse_rejects_junk(self):
        with self.assertRaises(ReleaseError):
            parse_version("1.2")

    def test_bump_patch(self):
        self.assertEqual(str(bump(Version(0, 1, 0), "patch")), "0.1.1")

    def test_bump_minor_resets_patch(self):
        self.assertEqual(str(bump(Version(0, 1, 4), "minor")), "0.2.0")

    def test_bump_major_resets(self):
        self.assertEqual(str(bump(Version(0, 9, 3), "major")), "1.0.0")

    def test_bump_rejects_bad_kind(self):
        with self.assertRaises(ReleaseError):
            bump(Version(0, 1, 0), "huge")


class TestVersionFiles(unittest.TestCase):
    def _tmp(self, name, content):
        d = tempfile.mkdtemp()
        p = Path(d) / name
        p.write_text(content)
        return p

    def test_json_pointer(self):
        p = self._tmp("package.json", '{\n  "name": "x",\n  "version": "0.1.0"\n}\n')
        self.assertEqual(read_version_file(p, "json", pointer="/version"), "0.1.0")
        write_version_file(p, "json", "0.2.0", pointer="/version")
        self.assertEqual(json.loads(p.read_text())["version"], "0.2.0")
        # name preserved
        self.assertEqual(json.loads(p.read_text())["name"], "x")

    def test_toml_key(self):
        p = self._tmp("Cargo.toml", '[package]\nname = "x"\nversion = "0.1.0"\n\n[deps]\nversion = "9.9.9"\n')
        self.assertEqual(read_version_file(p, "toml", key="package.version"), "0.1.0")
        write_version_file(p, "toml", "0.2.0", key="package.version")
        self.assertIn('version = "0.2.0"', p.read_text())
        # the unrelated [deps] version must NOT change
        self.assertIn('[deps]\nversion = "9.9.9"', p.read_text())

    def test_missing_field_errors(self):
        p = self._tmp("package.json", '{"name":"x"}')
        with self.assertRaises(Exception):
            read_version_file(p, "json", pointer="/version")

    def test_json_refuses_ambiguous_same_name_key(self):
        # A sibling object with the SAME key name AND value must not be silently
        # rewritten — the engine errors instead of guessing.
        p = self._tmp(
            "package.json",
            '{\n  "version": "0.1.0",\n  "dep": { "version": "0.1.0" }\n}\n',
        )
        with self.assertRaises(ReleaseError):
            write_version_file(p, "json", "0.2.0", pointer="/version")

    def test_toml_does_not_touch_other_section(self):
        p = self._tmp(
            "Cargo.toml",
            '[package]\nname = "x"\nversion = "0.1.0"\n\n[deps]\nversion = "0.1.0"\n',
        )
        write_version_file(p, "toml", "0.2.0", key="package.version")
        txt = p.read_text()
        self.assertIn('[package]\nname = "x"\nversion = "0.2.0"', txt)
        self.assertIn('[deps]\nversion = "0.1.0"', txt)  # untouched even with same value

    def test_write_is_idempotent_when_unchanged(self):
        p = self._tmp("package.json", '{"version":"0.2.0"}')
        write_version_file(p, "json", "0.2.0", pointer="/version")  # no error
        self.assertEqual(json.loads(p.read_text())["version"], "0.2.0")


class TestChangelog(unittest.TestCase):
    def test_buckets_by_type(self):
        commits = [
            "feat(mcp): add tag scopes",
            "fix: stop key leak",
            "perf(db): sql folders",
            "chore: bump dep",
            "docs: tweak",
        ]
        md = draft_changelog("0.2.0", "2026-06-03", commits)
        self.assertIn("## [0.2.0] - 2026-06-03", md)
        self.assertIn("### Added", md)
        self.assertIn("add tag scopes", md)
        self.assertIn("### Fixed", md)
        self.assertIn("stop key leak", md)
        self.assertIn("### Changed", md)
        # chores/docs excluded
        self.assertNotIn("bump dep", md)
        self.assertNotIn("tweak", md)

    def test_breaking_bang_goes_to_changed(self):
        md = draft_changelog("1.0.0", "2026-06-03", ["feat!: drop old api"])
        self.assertIn("### Changed", md)
        self.assertIn("drop old api", md)

    def test_empty_when_only_chores(self):
        md = draft_changelog("0.1.1", "2026-06-03", ["chore: x", "ci: y"])
        self.assertIn("## [0.1.1] - 2026-06-03", md)
        self.assertNotIn("###", md)


class TestSurfaceGate(unittest.TestCase):
    def test_breaking_stable_forces_major(self):
        self.assertEqual(
            required_bump([{"id": "db", "tier": "stable", "breaking": True}]), "major"
        )

    def test_breaking_preview_is_minor(self):
        self.assertEqual(
            required_bump([{"id": "mcp", "tier": "preview", "breaking": True}]), "minor"
        )

    def test_additive_is_minor(self):
        self.assertEqual(
            required_bump([{"id": "db", "tier": "stable", "breaking": False}]), "minor"
        )

    def test_nothing_is_patch(self):
        self.assertEqual(required_bump([]), "patch")

    def test_enforce_rejects_too_small(self):
        with self.assertRaises(ReleaseError):
            enforce_bump(requested="patch", required="major")

    def test_enforce_allows_equal_or_larger(self):
        enforce_bump(requested="major", required="minor")  # no raise
        enforce_bump(requested="minor", required="minor")  # no raise


class TestConfig(unittest.TestCase):
    def _cfg(self, obj):
        d = tempfile.mkdtemp()
        p = Path(d) / "release.config.json"
        p.write_text(json.dumps(obj))
        return p

    def test_loads_and_validates(self):
        p = self._cfg({
            "versionFiles": [{"path": "package.json", "kind": "json", "pointer": "/version"}],
            "gate": "true",
            "compatibility": {"path": "docs/COMPATIBILITY.md"},
            "surfaces": [{"id": "db", "name": "DB", "tier": "stable", "mode": "BACKWARD_TRANSITIVE"}],
            "tag": {"prefix": "v", "push": True},
        })
        cfg = load_config(p)
        self.assertEqual(cfg["gate"], "true")
        self.assertEqual(cfg["surfaces"][0]["tier"], "stable")

    def test_rejects_bad_tier(self):
        p = self._cfg({
            "versionFiles": [{"path": "p", "kind": "json", "pointer": "/version"}],
            "gate": "true",
            "compatibility": {"path": "x"},
            "surfaces": [{"id": "db", "name": "DB", "tier": "GA", "mode": "x"}],
            "tag": {"prefix": "v"},
        })
        with self.assertRaises(ReleaseError):
            load_config(p)

    def test_rejects_missing_key(self):
        p = self._cfg({"gate": "true"})
        with self.assertRaises(ReleaseError):
            load_config(p)

    def test_rejects_json_versionfile_without_pointer(self):
        p = self._cfg({
            "versionFiles": [{"path": "package.json", "kind": "json"}],
            "gate": "true", "compatibility": {"path": "x"},
            "surfaces": [], "tag": {"prefix": "v"},
        })
        with self.assertRaises(ReleaseError):
            load_config(p)

    def test_rejects_unknown_versionfile_kind(self):
        p = self._cfg({
            "versionFiles": [{"path": "x.yaml", "kind": "yaml", "pointer": "/version"}],
            "gate": "true", "compatibility": {"path": "x"},
            "surfaces": [], "tag": {"prefix": "v"},
        })
        with self.assertRaises(ReleaseError):
            load_config(p)


class TestPlan(unittest.TestCase):
    def test_build_plan(self):
        cfg = {
            "versionFiles": [{"path": "package.json", "kind": "json", "pointer": "/version"}],
            "tag": {"prefix": "v"},
        }
        plan = build_plan(cfg, current="0.1.0", kind="minor")
        self.assertEqual(plan["new_version"], "0.2.0")
        self.assertEqual(plan["tag"], "v0.2.0")
        self.assertIn("package.json", plan["files"])


if __name__ == "__main__":
    unittest.main()

# Compatibility Policy — {{PROJECT}}

{{PROJECT}} follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
This document declares the **public API** — the surfaces we promise to keep
working — and is updated on every release.

**The promise:** within a major version, anything written by an earlier `X.y.z`
keeps working under every later `X.*`. A change that breaks a `stable` surface
requires a new major version. (Modeled on the
[Go 1 Compatibility Promise](https://go.dev/doc/go1compat).)

Tiers: `experimental` (no promise) → `preview` (may change, with notice) →
`stable` (the promise applies).

## Surfaces

| Surface | Tier | Since | Mode | Notes |
|---|---|---|---|---|
| {{SURFACE_NAME}} | preview | — | unversioned | — |

## Deprecations

| Item | Deprecated in | Removable in | Replacement |
|---|---|---|---|
| — | — | — | — |

## 1.0 readiness gate

- [ ] Every surface is `stable` with a declared compatibility mode.
- [ ] Each `stable` surface has golden/contract tests in the release gate.
- [ ] A deprecation process is documented and used.

Last updated: 0.1.0 ({{DATE}})

# Contracts & Modes — {{PROJECT}}

How we make compatibility **mechanically true** instead of merely promised. This
is the third formulation in the release policy (after "The Promise" and "Tiers &
Gates"): declare a compatibility **mode** per surface, then enforce it with tests
that fail the build.

## Vocabulary (from schema registries)

- **Backward** — new code reads old data/messages.
- **Forward** — old code tolerates new data (ignore unknown fields).
- **Full** — both. **`_TRANSITIVE`** — checked against *all* prior versions.

Refs: [Schema-Registry compatibility](https://docs.confluent.io/platform/current/schema-registry/fundamentals/schema-evolution.html),
[Pact (consumer-driven contracts)](https://docs.pact.io/).

## The pattern (golden test)

1. **Freeze** an artifact produced by an older version (a DB, an export, a recorded API exchange).
2. **Exercise** it with current code.
3. **Assert** it still works (opens / serves / validates).

Wire each golden test into `release.config.json → extraGate` so a release can't
ship if compatibility broke.

## Add the next contract test

- [ ] {{FIRST_GOLDEN_TEST}} — the worked example.
- [ ] Export round-trip: serve a frozen package, assert it renders.
- [ ] API: record consumer expectations; verify the provider still satisfies them.

{
  "versionFiles": [
    { "path": "package.json", "kind": "json", "pointer": "/version" }
  ],
  "lockfiles": [],
  "gate": "{{GATE_COMMAND}}",
  "extraGate": [],
  "changelog": { "path": "CHANGELOG.md", "style": "keep-a-changelog", "from": "conventional-commits" },
  "compatibility": { "path": "docs/COMPATIBILITY.md" },
  "surfaces": [
    { "id": "{{SURFACE_ID}}", "name": "{{SURFACE_NAME}}", "tier": "preview", "mode": "unversioned" }
  ],
  "releaseBranch": "main",
  "tag": { "prefix": "v", "push": true }
}