Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

6.2 KB
Raw Blame
#!/usr/bin/env python3
"""Validate exact, reviewed canonical-completion pairs without rewriting history."""

from __future__ import annotations

import argparse
import json
import os
from pathlib import Path
import re
import subprocess
import sys
import tempfile


REPO_ROOT = Path(__file__).resolve().parents[2]
REGISTRY = Path(__file__).with_name("canonical_completion_history.json")
SHA_PATTERN = re.compile(r"[0-9a-f]{40}")

# The proof sandbox strips the maintainer read config, and a linked worktree's
# gitdir lives outside the checkout. A private config restores the fixed
# safe.directory policy for the clone without trusting worker-written state.
_GIT_ENV: dict[str, str] | None = None


def git_env() -> dict[str, str]:
    global _GIT_ENV
    if _GIT_ENV is None:
        handle, path = tempfile.mkstemp(prefix="pulse-completion-gitconfig-")
        with os.fdopen(handle, "w", encoding="utf-8") as stream:
            stream.write("[safe]\n\tdirectory = *\n")
        _GIT_ENV = {
            **os.environ,
            "GIT_CONFIG_GLOBAL": path,
            "GIT_CONFIG_NOSYSTEM": "1",
        }
    return _GIT_ENV


def git(*args: str, cwd: Path = REPO_ROOT) -> str:
    return subprocess.run(
        ["git", *args],
        cwd=cwd,
        env=git_env(),
        check=True,
        capture_output=True,
        text=True,
    ).stdout.rstrip("\n")


def load_completions(path: Path = REGISTRY) -> dict[str, dict[str, str]]:
    document = json.loads(path.read_text(encoding="utf-8"))
    if not isinstance(document, dict) or set(document) != {"version", "completions"}:
        raise ValueError("completion registry must contain only version and completions")
    if document["version"] != 1 or isinstance(document["version"], bool):
        raise ValueError("unsupported completion registry version")
    if not isinstance(document["completions"], list):
        raise ValueError("completion registry entries must be a list")

    result: dict[str, dict[str, str]] = {}
    required = {"incomplete_commit", "completion_commit", "reason"}
    for entry in document["completions"]:
        if not isinstance(entry, dict) or set(entry) != required:
            raise ValueError("completion entry has unexpected fields")
        if not all(isinstance(entry[field], str) and entry[field].strip() for field in required):
            raise ValueError("completion entry fields must be non-empty strings")
        incomplete = entry["incomplete_commit"]
        completion = entry["completion_commit"]
        if not SHA_PATTERN.fullmatch(incomplete) or not SHA_PATTERN.fullmatch(completion):
            raise ValueError("completion entry revisions must be full lowercase commit IDs")
        if incomplete == completion or incomplete in result:
            raise ValueError("completion entries must identify distinct, unique commits")
        result[incomplete] = entry
    return result


def changed_files(commit: str) -> list[str]:
    return [
        line
        for line in git("diff-tree", "--no-commit-id", "--name-only", "-r", commit).splitlines()
        if line
    ]


def validate_completion(incomplete: str, head: str) -> bool:
    """Return False for an ordinary commit; validate and return True for a registered pair."""
    entry = load_completions().get(incomplete)
    if entry is None:
        return False
    if not SHA_PATTERN.fullmatch(head):
        raise ValueError("head must be a full lowercase commit ID")

    completion = entry["completion_commit"]
    git("cat-file", "-e", f"{incomplete}^{{commit}}")
    git("cat-file", "-e", f"{completion}^{{commit}}")
    git("cat-file", "-e", f"{head}^{{commit}}")
    subprocess.run(
        ["git", "merge-base", "--is-ancestor", incomplete, completion],
        cwd=REPO_ROOT,
        env=git_env(),
        check=True,
    )
    subprocess.run(
        ["git", "merge-base", "--is-ancestor", completion, head],
        cwd=REPO_ROOT,
        env=git_env(),
        check=True,
    )

    files = sorted(set(changed_files(incomplete) + changed_files(completion)))
    with tempfile.TemporaryDirectory(prefix="pulse-canonical-completion-") as temp:
        worktree = Path(temp) / "pulse"
        # Materialise the completion tree with a shared clone rather than a
        # linked worktree. A linked worktree writes its administrative files
        # into the reviewed repository's git directory, which is read-only
        # inside the maintainer proof sandbox. A shared clone reads the
        # reviewed objects through alternates and writes only inside the
        # disposable temporary directory, so CI and the maintainer preflight
        # validate the pair identically without relaxing that boundary.
        git("clone", "--quiet", "--shared", "--no-checkout", "--local",
            str(REPO_ROOT), str(worktree))
        git("-C", str(worktree), "checkout", "--quiet", "--detach", completion)
        guard = worktree / "scripts/release_control/canonical_completion_guard.py"
        result = subprocess.run(
            [
                sys.executable,
                str(guard),
                "--files-from-stdin",
                "--diff-base",
                f"{incomplete}^",
                "--commit",
                completion,
            ],
            cwd=worktree,
            input="".join(f"{path}\n" for path in files),
            text=True,
        )
        if result.returncode != 0:
            raise ValueError(
                f"registered completion {completion} does not complete {incomplete}"
            )

    print(
        "Canonical completion history passed "
        f"({incomplete} completed by {completion}: {entry['reason']})"
    )
    return True


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--commit", required=True)
    parser.add_argument("--head", required=True)
    return parser.parse_args()


def main() -> int:
    args = parse_args()
    try:
        return 0 if validate_completion(args.commit, args.head) else 3
    except (OSError, ValueError, subprocess.CalledProcessError, json.JSONDecodeError) as error:
        print(f"Canonical completion history failed: {error}", file=sys.stderr)
        return 1


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