platform-ci/platform_ci/source_helpers.py

"""Prove the native source-check helpers are the reviewed, receipted files before they run.

`source_checks/check-source.mjs` and `jsonc.mjs` are vendored byte for byte from the reviewed source at the revision named in
`source_checks/receipt.json`; the adapter never ports, wraps or edits them. Before the `source` tool starts the program, this module
requires both files to sit together in the platform checkout and to match the receipt's SHA-256, so a changed or missing helper
stops the run instead of silently changing what a source check means.
"""

import hashlib
import json
from pathlib import Path
from typing import Final, cast

from platform_ci.workspace import PipelineError

RECEIPT_PATH: Final = Path(__file__).resolve().parent.parent / "source_checks" / "receipt.json"


class SourceHelperError(PipelineError):
   """Raised when a native source-check helper is missing or differs from its receipt."""


def verify_source_helpers(directory: Path, receipt_path: Path = RECEIPT_PATH) -> None:
   """Require every receipted helper to exist in `directory` with exactly its recorded SHA-256."""
   try:
      receipt = cast("dict[str, object]", json.loads(receipt_path.read_text(encoding="utf-8")))
      expected = cast("dict[str, str]", receipt["files"])
   except (OSError, ValueError, KeyError) as error:
      raise SourceHelperError(f"the source-check receipt {receipt_path.name} cannot be read: {type(error).__name__}") from error
   for name, digest in sorted(expected.items()):
      path = directory / name
      if path.is_symlink() or not path.is_file():
         raise SourceHelperError(f"source-check helper {name} is missing beside the program")
      if hashlib.sha256(path.read_bytes()).hexdigest() != digest:
         raise SourceHelperError(f"source-check helper {name} differs from its receipted revision")