sanitize-commit.py

#!/usr/bin/env python3
"""
sanitize-commit.py

Pre-commit sanity checker for the Serial Studio Extensions repository.

Validates:
  - manifest.json parses, references existing info.json files
  - Each info.json parses and has the required fields
  - Files declared in info.json (entry, files, icon, screenshot) exist
  - Platform-specific entry/files exist on disk
  - Plugin runtime wrappers (run.sh, run.cmd) exist when referenced
  - No duplicate extension IDs across the manifest
  - Theme color JSON and code-editor XML files exist
  - Python files are formatted with black (auto-formats; reports diff count)

Exit code: 0 if all checks pass, 1 if any error is found.

Usage:
    python3 sanitize-commit.py [--check]   # don't reformat, fail on diff
    python3 sanitize-commit.py             # reformat in place

Requires:
    pip install black
"""

from __future__ import annotations

import argparse
import json
import shutil
import subprocess
import sys
from pathlib import Path
from typing import Iterable

REPO_ROOT = Path(__file__).resolve().parent
MANIFEST = REPO_ROOT / "manifest.json"

REQUIRED_INFO_FIELDS = {"id", "type", "title", "version"}
PLUGIN_REQUIRED_FIELDS = REQUIRED_INFO_FIELDS | {"entry", "files"}
THEME_REQUIRED_FIELDS = REQUIRED_INFO_FIELDS | {"files"}
VALID_TYPES = {"plugin", "theme"}


class Reporter:
    def __init__(self) -> None:
        self.errors: list[str] = []
        self.warnings: list[str] = []

    def error(self, msg: str) -> None:
        self.errors.append(msg)
        print(f"  ERROR: {msg}", file=sys.stderr)

    def warn(self, msg: str) -> None:
        self.warnings.append(msg)
        print(f"  WARN:  {msg}")

    def section(self, title: str) -> None:
        print(f"\n=== {title} ===")

    def info(self, msg: str) -> None:
        print(f"  {msg}")

    def ok(self) -> bool:
        return not self.errors


def load_json(path: Path, reporter: Reporter) -> dict | None:
    try:
        return json.loads(path.read_text(encoding="utf-8"))
    except FileNotFoundError:
        reporter.error(f"missing file: {path.relative_to(REPO_ROOT)}")
    except json.JSONDecodeError as e:
        reporter.error(
            f"invalid JSON in {path.relative_to(REPO_ROOT)}: {e.msg} "
            f"at line {e.lineno} col {e.colno}"
        )
    except OSError as e:
        reporter.error(f"cannot read {path.relative_to(REPO_ROOT)}: {e}")
    return None


def check_paths_exist(base: Path, paths: Iterable[str], reporter: Reporter) -> None:
    for rel in paths:
        if not rel:
            continue
        target = base / rel
        if not target.exists():
            reporter.error(
                f"declared file does not exist: "
                f"{target.relative_to(REPO_ROOT).as_posix()}"
            )


def validate_info(info_path: Path, reporter: Reporter) -> dict | None:
    info = load_json(info_path, reporter)
    if info is None:
        return None

    base = info_path.parent
    rel = info_path.relative_to(REPO_ROOT).as_posix()

    type_ = info.get("type")
    if type_ not in VALID_TYPES:
        reporter.error(
            f"{rel}: type must be one of {sorted(VALID_TYPES)}, got {type_!r}"
        )
        return info

    required = PLUGIN_REQUIRED_FIELDS if type_ == "plugin" else THEME_REQUIRED_FIELDS
    missing = required - set(info.keys())
    if missing:
        reporter.error(f"{rel}: missing required fields: {sorted(missing)}")

    expected_id = info_path.parent.name
    if info.get("id") != expected_id:
        reporter.error(
            f"{rel}: id={info.get('id')!r} does not match directory name "
            f"{expected_id!r}"
        )

    files = info.get("files", [])
    if not isinstance(files, list):
        reporter.error(f"{rel}: 'files' must be a list")
        files = []
    check_paths_exist(base, files, reporter)

    for opt in ("icon", "screenshot"):
        v = info.get(opt)
        if v:
            check_paths_exist(base, [v], reporter)

    if type_ == "plugin":
        entry = info.get("entry")
        if entry:
            check_paths_exist(base, [entry], reporter)

        platforms = info.get("platforms", {})
        if not isinstance(platforms, dict):
            reporter.error(f"{rel}: 'platforms' must be an object")
            platforms = {}

        for key, spec in platforms.items():
            if not isinstance(spec, dict):
                reporter.error(f"{rel}: platforms[{key!r}] must be an object")
                continue
            p_entry = spec.get("entry")
            if p_entry:
                check_paths_exist(base, [p_entry], reporter)
            p_files = spec.get("files", [])
            if not isinstance(p_files, list):
                reporter.error(f"{rel}: platforms[{key!r}].files must be a list")
            else:
                check_paths_exist(base, p_files, reporter)

        deps = info.get("dependencies", [])
        if not isinstance(deps, list):
            reporter.error(f"{rel}: 'dependencies' must be a list")
        else:
            for i, d in enumerate(deps):
                if not isinstance(d, dict):
                    reporter.error(f"{rel}: dependencies[{i}] must be an object")
                    continue
                if "name" not in d or "executables" not in d:
                    reporter.error(
                        f"{rel}: dependencies[{i}] missing 'name' or 'executables'"
                    )

    elif type_ == "theme":
        # Theme should reference a color JSON and a code-editor XML
        ext_id = info.get("id", "")
        color_json = base / f"{ext_id}.json"
        if not color_json.exists():
            reporter.error(
                f"{rel}: theme color palette not found at "
                f"{color_json.relative_to(REPO_ROOT).as_posix()}"
            )
        else:
            palette = load_json(color_json, reporter)
            if palette and "colors" not in palette:
                reporter.warn(
                    f"{color_json.relative_to(REPO_ROOT).as_posix()}: "
                    f"missing 'colors' object"
                )
            if palette:
                editor_id = (
                    palette.get("parameters", {}).get("code-editor-theme") or ext_id
                )
                editor_xml = base / "code-editor" / f"{editor_id}.xml"
                if not editor_xml.exists():
                    reporter.error(
                        f"{rel}: code editor theme XML not found at "
                        f"{editor_xml.relative_to(REPO_ROOT).as_posix()}"
                    )

    return info


def validate_manifest(reporter: Reporter) -> list[Path]:
    reporter.section(f"manifest.json")
    manifest = load_json(MANIFEST, reporter)
    if manifest is None:
        return []

    if manifest.get("version") != 1:
        reporter.error(f"manifest.json: version must be 1")

    paths = manifest.get("extensions", [])
    if not isinstance(paths, list):
        reporter.error("manifest.json: 'extensions' must be a list")
        return []

    info_paths: list[Path] = []
    seen = set()
    for rel in paths:
        if rel in seen:
            reporter.error(f"manifest.json: duplicate entry {rel!r}")
            continue
        seen.add(rel)
        p = REPO_ROOT / rel
        if not p.exists():
            reporter.error(f"manifest.json: missing info.json {rel!r}")
            continue
        info_paths.append(p)

    # Check the inverse: every info.json on disk should be in the manifest
    on_disk = sorted(REPO_ROOT.glob("plugin/*/info.json")) + sorted(
        REPO_ROOT.glob("theme/*/info.json")
    )
    on_disk_rel = {p.relative_to(REPO_ROOT).as_posix() for p in on_disk}
    in_manifest = set(paths)
    orphans = on_disk_rel - in_manifest
    for orphan in sorted(orphans):
        # _template directories are intentionally excluded
        if "/_template/" in orphan or orphan.startswith("_template/"):
            continue
        reporter.warn(f"info.json on disk but not in manifest: {orphan}")

    reporter.info(f"{len(info_paths)} extension(s) listed")
    return info_paths


def validate_extensions(info_paths: list[Path], reporter: Reporter) -> None:
    ids: dict[str, str] = {}
    for info_path in info_paths:
        rel = info_path.relative_to(REPO_ROOT).as_posix()
        reporter.section(rel)
        info = validate_info(info_path, reporter)
        if not info:
            continue

        ext_id = info.get("id")
        if ext_id and ext_id in ids:
            reporter.error(f"duplicate id {ext_id!r}: also used by {ids[ext_id]}")
        elif ext_id:
            ids[ext_id] = rel


def find_python_files() -> list[Path]:
    out: list[Path] = []
    for root in (REPO_ROOT / "plugin", REPO_ROOT / "theme"):
        if not root.exists():
            continue
        for p in root.rglob("*.py"):
            # Skip generated protobuf files
            name = p.name
            if name.endswith("_pb2.py") or name.endswith("_pb2_grpc.py"):
                continue
            out.append(p)
    # Include sibling scripts at repo root
    for p in REPO_ROOT.glob("*.py"):
        out.append(p)
    return sorted(set(out))


def run_black(files: list[Path], check_only: bool, reporter: Reporter) -> None:
    reporter.section("black")
    if not files:
        reporter.info("no Python files to format")
        return

    if shutil.which("black") is None:
        reporter.error("black not found in PATH (pip install black)")
        return

    cmd = ["black", "--quiet"]
    if check_only:
        cmd.append("--check")
    cmd.extend(str(f) for f in files)

    result = subprocess.run(cmd, cwd=REPO_ROOT)
    if result.returncode == 0:
        reporter.info(f"{len(files)} file(s) clean")
    elif check_only and result.returncode == 1:
        reporter.error("some files would be reformatted by black (run without --check)")
    elif result.returncode != 0:
        reporter.error(f"black exited with code {result.returncode}")


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__.strip().splitlines()[0])
    parser.add_argument(
        "--check",
        action="store_true",
        help="don't reformat Python files; fail if black would make changes",
    )
    parser.add_argument(
        "--no-format",
        action="store_true",
        help="skip the black formatting step entirely",
    )
    args = parser.parse_args()

    reporter = Reporter()
    info_paths = validate_manifest(reporter)
    validate_extensions(info_paths, reporter)

    if not args.no_format:
        py_files = find_python_files()
        run_black(py_files, args.check, reporter)

    print()
    if reporter.ok():
        print(f"OK ({len(reporter.warnings)} warning(s))")
        return 0

    print(
        f"FAILED: {len(reporter.errors)} error(s), "
        f"{len(reporter.warnings)} warning(s)",
        file=sys.stderr,
    )
    return 1


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