scripts/submission_preflight.py

"""Hackathon submission preflight checks.

Usage:
    python scripts/submission_preflight.py

Fails fast if the repo is missing judge-critical submission signals.
"""
from __future__ import annotations

import re
import sys
from pathlib import Path


REPO_ROOT = Path(__file__).resolve().parent.parent
README = REPO_ROOT / "README.md"
MANIFEST = REPO_ROOT / "openenv.yaml"
SPACE_DOCKERFILE = REPO_ROOT / "space" / "Dockerfile"


def _read(path: Path) -> str:
    if not path.exists():
        raise FileNotFoundError(str(path))
    return path.read_text(encoding="utf-8")


def _check(condition: bool, ok_msg: str, fail_msg: str, errors: list[str]) -> None:
    if condition:
        print(f"[OK] {ok_msg}")
    else:
        print(f"[FAIL] {fail_msg}")
        errors.append(fail_msg)


def main() -> int:
    errors: list[str] = []

    _check(README.exists(), "README.md exists", "README.md is missing", errors)
    _check(MANIFEST.exists(), "openenv.yaml exists", "openenv.yaml is missing", errors)
    _check(
        SPACE_DOCKERFILE.exists(),
        "space/Dockerfile exists",
        "space/Dockerfile is missing",
        errors,
    )

    if README.exists():
        text = _read(README)
        _check(
            "Environment endpoint URL" in text,
            "README includes environment endpoint section",
            "README is missing environment endpoint section",
            errors,
        )
        _check(
            "https://huggingface.co/spaces/" in text,
            "README includes HF Space link",
            "README is missing HF Space link",
            errors,
        )
        _check(
            "healthz" in text,
            "README includes health check link/command",
            "README is missing health check instructions",
            errors,
        )
        _check(
            "TODO (" not in text,
            "README has no placeholder TODO links",
            "README still contains TODO placeholders; replace them before final submit",
            errors,
        )
        _check(
            "reward curve" in text.lower() or "reward curves" in text.lower(),
            "README mentions training-evidence plots",
            "README does not mention reward/loss evidence plots",
            errors,
        )
        _check(
            bool(re.search(r"https://[A-Za-z0-9.-]+\.hf\.space", text)),
            "README includes an hf.space endpoint URL",
            "README is missing a concrete hf.space endpoint URL",
            errors,
        )

    if MANIFEST.exists():
        manifest = _read(MANIFEST)
        _check(
            "entrypoint:" in manifest,
            "openenv.yaml has entrypoint",
            "openenv.yaml missing entrypoint",
            errors,
        )
        _check(
            "name:" in manifest and "version:" in manifest,
            "openenv.yaml has name/version",
            "openenv.yaml missing name/version fields",
            errors,
        )

    print()
    if errors:
        print(f"Preflight failed with {len(errors)} issue(s).")
        return 1
    print("Preflight passed. Submission package looks judge-ready.")
    return 0


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