Skip to content

Editorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, Qoder, and Pi. 45 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop.

5.5 KB
Raw Blame
#!/usr/bin/env python3
"""Inspect synchronized plugin-version changes across git history."""

from __future__ import annotations

import argparse
import json
import re
import subprocess
import sys
from pathlib import Path
from typing import Sequence, Tuple

ROOT = Path(__file__).resolve().parent.parent
MANIFEST_PATHS = (
    Path(".claude-plugin/plugin.json"),
    Path(".codex-plugin/plugin.json"),
    Path(".factory-plugin/plugin.json"),
    Path(".qoder-plugin/plugin.json"),
)
QODER_MANIFEST_PATH = Path(".qoder-plugin/plugin.json")
SEMVER = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$")


class VersionHistoryError(ValueError):
    """Raised when version history cannot be inspected safely."""


def git(root: Path, *args: str) -> str:
    result = subprocess.run(
        ["git", *args],
        cwd=root,
        text=True,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
    )
    if result.returncode:
        detail = result.stderr.strip() or result.stdout.strip()
        raise VersionHistoryError(f"git {' '.join(args)} failed: {detail}")
    return result.stdout.strip()


def qoder_predates_manifest(root: Path, ref: str) -> bool:
    """Return whether ref is from before Qoder's manifest entered its history."""
    additions = git(
        root,
        "log",
        "--all",
        "--diff-filter=A",
        "--format=%H",
        "--",
        QODER_MANIFEST_PATH.as_posix(),
    ).splitlines()
    if not additions:
        return False
    introduction = additions[-1]
    result = subprocess.run(
        ["git", "merge-base", "--is-ancestor", introduction, ref],
        cwd=root,
        stdout=subprocess.DEVNULL,
        stderr=subprocess.PIPE,
        text=True,
    )
    if result.returncode == 0:
        return False
    if result.returncode == 1:
        return True
    detail = result.stderr.strip()
    raise VersionHistoryError(
        f"could not compare Qoder manifest introduction with {ref}: {detail}"
    )


def versions_at(root: Path, ref: str) -> Tuple[str, ...]:
    entries: list[tuple[Path, str]] = []
    for relative in MANIFEST_PATHS:
        exists = subprocess.run(
            ["git", "cat-file", "-e", f"{ref}:{relative.as_posix()}"],
            cwd=root,
            stdout=subprocess.DEVNULL,
            stderr=subprocess.DEVNULL,
        )
        if exists.returncode != 0:
            if relative == QODER_MANIFEST_PATH and qoder_predates_manifest(root, ref):
                continue
            raise VersionHistoryError(f"{relative} is missing at {ref}")
        raw = git(root, "show", f"{ref}:{relative.as_posix()}")
        try:
            payload = json.loads(raw)
        except json.JSONDecodeError as exc:
            raise VersionHistoryError(
                f"{relative} at {ref} is not valid JSON: {exc}"
            ) from exc
        if not isinstance(payload, dict):
            raise VersionHistoryError(f"{relative} at {ref} must contain an object")
        version = payload.get("version")
        if not isinstance(version, str) or SEMVER.fullmatch(version) is None:
            raise VersionHistoryError(
                f"{relative} at {ref} has an invalid version: {version!r}"
            )
        entries.append((relative, version))
    if not entries:
        raise VersionHistoryError(f"no plugin manifests found at {ref}")
    versions = tuple(version for _, version in entries)
    if len(set(versions)) != 1:
        rendered = ", ".join(
            f"{path}={version}" for path, version in entries
        )
        raise VersionHistoryError(
            f"manifest versions at {ref} are not synchronized: {rendered}"
        )
    return versions


def versions_changed(root: Path, before: str, after: str) -> bool:
    return versions_at(root, before)[0] != versions_at(root, after)[0]


def first_parent(root: Path, commit: str) -> str | None:
    fields = git(root, "rev-list", "--parents", "-n", "1", commit).split()
    return fields[1] if len(fields) > 1 else None


def last_version_bump(root: Path, source: str) -> str:
    commits = git(
        root,
        "rev-list",
        "--first-parent",
        source,
        "--",
        *(path.as_posix() for path in MANIFEST_PATHS),
    ).splitlines()
    for commit in commits:
        parent = first_parent(root, commit)
        if parent is not None and versions_changed(root, parent, commit):
            return commit
    raise VersionHistoryError(
        f"no synchronized plugin version bump found at {source}"
    )


def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
    parser = argparse.ArgumentParser(description=__doc__)
    subparsers = parser.add_subparsers(dest="command", required=True)
    changed = subparsers.add_parser(
        "changed", help="print whether synchronized versions differ between two refs"
    )
    changed.add_argument("before")
    changed.add_argument("after")
    last = subparsers.add_parser(
        "last-bump", help="print the newest first-parent commit with a version change"
    )
    last.add_argument("source")
    return parser.parse_args(argv)


def main(argv: Sequence[str] | None = None) -> int:
    args = parse_args(argv)
    try:
        if args.command == "changed":
            changed = versions_changed(ROOT, args.before, args.after)
            print("true" if changed else "false")
        else:
            print(last_version_bump(ROOT, args.source))
    except VersionHistoryError as exc:
        print(f"ERROR: {exc}", file=sys.stderr)
        return 1
    return 0


if __name__ == "__main__":
    raise SystemExit(main())