claude-dev-env 4.3.0 → 7.1.0

package/scripts/local_verification/config/constants.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+MANIFEST_VERSION = 1
+MANIFEST_VERSION_KEY = "version"
+MANIFEST_CHECKS_KEY = "checks"
+MANIFEST_EXCLUSIONS_KEY = "exclusions"
+CHECK_ID_KEY = "id"
+CHECK_ARGUMENTS_KEY = "argv"
+CHECK_DIRECTORY_KEY = "cwd"
+CHECK_TIMEOUT_KEY = "timeout_seconds"
+CHECK_MINIMUM_TESTS_KEY = "minimum_tests"
+EXCLUSION_SELECTOR_KEY = "selector"
+EXCLUSION_REASON_KEY = "reason"
+MANIFEST_DIGEST_ALGORITHM = "sha256"
+ALL_MANIFEST_DIGEST_SEPARATORS = (",", ":")
+SUCCESS_EXIT_CODE = 0
+CHECK_FAILED_EXIT_CODE = 1
+INVALID_INPUT_EXIT_CODE = 2
+INCOMPLETE_EXIT_CODE = 3
+UTF8_ENCODING = "utf-8"
+JSON_INDENT_SPACES = 2
+PASSED_STATUS = "passed"
+FAILED_STATUS = "failed"
+INCOMPLETE_STATUS = "incomplete"
+MINIMUM_TESTS_ERROR_KIND = "minimum_tests"
+MISSING_TOOL_ERROR_KIND = "missing_tool"
+TIMEOUT_ERROR_KIND = "timeout"
+CRASH_ERROR_KIND = "crash"
+START_ERROR_KIND = "start_error"
+COLLECTION_ERROR_KIND = "collection_error"
+NONZERO_EXIT_ERROR_KIND = "nonzero_exit"
+SKIPPED_TESTS_ERROR_KIND = "skipped_tests"
+PYTEST_COLLECTION_FLAG = "--collect-only"
+PYTEST_QUIET_FLAG = "-q"
+COLLECTED_TESTS_PATTERN = re.compile(r"(?P<count>\d+) tests? collected")
+SKIPPED_TESTS_PATTERN = re.compile(r"(?P<count>\d+) skipped")
+SAFE_LOG_NAME_PATTERN = re.compile(r"[^A-Za-z0-9_.-]+")
+PYTHON_PLACEHOLDER = "{python}"
+REPOSITORY_PLACEHOLDER = "{repo}"
+BASE_PLACEHOLDER = "{base}"
+CDE_LINT_PLACEHOLDER = "{cde_lint}"
+REPOSITORY_POLICY_PLACEHOLDER = "{repository_policy}"
+LOGS_DIRECTORY_SUFFIX = ".logs"
+STDOUT_LOG_SUFFIX = ".stdout.log"
+STDERR_LOG_SUFFIX = ".stderr.log"
+COLLECTION_STDOUT_LOG_SUFFIX = ".collection.stdout.log"
+COLLECTION_STDERR_LOG_SUFFIX = ".collection.stderr.log"
+REPORT_NEWLINE = "\n"
+GIT_EXECUTABLE = "git"
+ALL_GIT_ROOT_ARGUMENTS = ("rev-parse", "--show-toplevel")
+ALL_GIT_HEAD_ARGUMENTS = ("rev-parse", "--verify", "HEAD")
+ALL_GIT_TREE_ARGUMENTS = ("rev-parse", "--verify", "HEAD^{tree}")
+ALL_GIT_BASE_ARGUMENT_PREFIX = ("rev-parse", "--verify")
+ALL_GIT_STATUS_ARGUMENTS = (
+    "status",
+    "--porcelain=v1",
+    "--untracked-files=all",
+)
+ALL_GIT_CHANGED_FILES_ARGUMENTS = ("diff", "--name-only", "-z")
+ALL_GIT_INDEX_CHANGED_FILES_ARGUMENTS = (
+    "diff",
+    "--cached",
+    "--name-only",
+    "-z",
+)
+ALL_GIT_UNTRACKED_FILES_ARGUMENTS = (
+    "ls-files",
+    "--others",
+    "--exclude-standard",
+    "-z",
+)
+GIT_COMMIT_OBJECT_SUFFIX = "^{commit}"
+GIT_PATH_SEPARATOR = b"\0"
+DIGEST_LENGTH_BYTES = 8
+DIGEST_BYTE_ORDER: Literal["big"] = "big"
+CLI_START_MESSAGE_TEMPLATE = "verification start: {report_path}"
+CLI_CHECK_START_MESSAGE_TEMPLATE = "check start: {check_id}"
+CLI_CHECK_FINISH_MESSAGE_TEMPLATE = "check finish: {check_id} status={status}"
+CLI_AGGREGATE_MESSAGE_TEMPLATE = "aggregate: {status}"
+CLI_REVISION_MESSAGE_TEMPLATE = "revision: head={head} base={base}"
+CLI_ELIGIBILITY_MESSAGE_TEMPLATE = "eligibility: clean={worktree_clean} unchanged={inputs_unchanged} publishable={publishable}"
+CLI_REPORT_MESSAGE_TEMPLATE = "report: {report_path}"
+CLI_FAILURE_MESSAGE_TEMPLATE = "verification {status}: required checks did not pass"
+UNRESOLVED_REVISION = "unresolved"
+RUN_LOG_FILENAME = "run.log"
+RUN_CHECK_LOG_TEMPLATE = "check {check_id} status={status}"

package/scripts/local_verification/config/timing.py

@@ -0,0 +1 @@
+GIT_METADATA_TIMEOUT_SECONDS = 5.0

package/scripts/local_verification/git_state.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import hashlib
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import (
+    ALL_GIT_BASE_ARGUMENT_PREFIX,
+    ALL_GIT_CHANGED_FILES_ARGUMENTS,
+    ALL_GIT_HEAD_ARGUMENTS,
+    ALL_GIT_INDEX_CHANGED_FILES_ARGUMENTS,
+    ALL_GIT_ROOT_ARGUMENTS,
+    ALL_GIT_STATUS_ARGUMENTS,
+    ALL_GIT_TREE_ARGUMENTS,
+    ALL_GIT_UNTRACKED_FILES_ARGUMENTS,
+    DIGEST_BYTE_ORDER,
+    DIGEST_LENGTH_BYTES,
+    GIT_COMMIT_OBJECT_SUFFIX,
+    GIT_EXECUTABLE,
+    GIT_PATH_SEPARATOR,
+    UTF8_ENCODING,
+)
+from .config.timing import GIT_METADATA_TIMEOUT_SECONDS
+
+
+@dataclass(frozen=True)
+class CandidateSnapshot:
+    head_revision: str | None
+    base_revision: str | None
+    is_git_repository: bool
+    worktree_clean: bool
+    input_digest: str | None
+
+
+def capture_candidate_snapshot(
+    repository_path: Path, base_revision: str
+) -> CandidateSnapshot:
+    """Capture Git revisions and candidate file contents at one point.
+
+    Args:
+        repository_path: Candidate repository root.
+        base_revision: Base revision supplied to the verification run.
+
+    Returns:
+        Git revision and candidate content facts for the snapshot.
+    """
+    git_root = _run_git_text(repository_path, ALL_GIT_ROOT_ARGUMENTS)
+    if git_root is None or Path(git_root).resolve() != repository_path.resolve():
+        return CandidateSnapshot(None, None, False, False, None)
+    head_revision = _run_git_text(repository_path, ALL_GIT_HEAD_ARGUMENTS)
+    resolved_base_revision = _run_git_text(
+        repository_path,
+        (*ALL_GIT_BASE_ARGUMENT_PREFIX, base_revision + GIT_COMMIT_OBJECT_SUFFIX),
+    )
+    status_bytes = _run_git_bytes(repository_path, ALL_GIT_STATUS_ARGUMENTS)
+    is_worktree_clean = status_bytes == b""
+    return CandidateSnapshot(
+        head_revision,
+        resolved_base_revision,
+        True,
+        is_worktree_clean,
+        _compute_input_digest(repository_path, is_worktree_clean),
+    )
+
+
+def _run_git_text(repository_path: Path, all_arguments: tuple[str, ...]) -> str | None:
+    command_bytes = _run_git_bytes(repository_path, all_arguments)
+    if command_bytes is None:
+        return None
+    revision_text = command_bytes.decode(UTF8_ENCODING).strip()
+    return revision_text or None
+
+
+def _run_git_bytes(
+    repository_path: Path, all_arguments: tuple[str, ...]
+) -> bytes | None:
+    try:
+        completed_process = subprocess.run(
+            [GIT_EXECUTABLE, *all_arguments],
+            cwd=repository_path,
+            capture_output=True,
+            check=False,
+            timeout=GIT_METADATA_TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if completed_process.returncode != 0:
+        return None
+    return completed_process.stdout
+
+
+def _compute_input_digest(repository_path: Path, is_worktree_clean: bool) -> str | None:
+    head_tree = _run_git_text(repository_path, ALL_GIT_TREE_ARGUMENTS)
+    if head_tree is None:
+        return None
+    input_digest = hashlib.sha256()
+    _add_digest_record(input_digest, head_tree.encode(UTF8_ENCODING))
+    if is_worktree_clean:
+        return input_digest.hexdigest()
+    all_changed_paths = _changed_input_paths(repository_path)
+    if all_changed_paths is None:
+        return None
+    for each_path_bytes in all_changed_paths:
+        input_path = repository_path / Path(each_path_bytes.decode(UTF8_ENCODING))
+        input_bytes = _read_input_bytes(input_path)
+        if input_bytes is None:
+            return None
+        _add_digest_record(input_digest, each_path_bytes)
+        _add_digest_record(input_digest, input_bytes)
+    return input_digest.hexdigest()
+
+
+def _changed_input_paths(repository_path: Path) -> tuple[bytes, ...] | None:
+    all_path_bytes: set[bytes] = set()
+    for each_arguments in (
+        ALL_GIT_CHANGED_FILES_ARGUMENTS,
+        ALL_GIT_INDEX_CHANGED_FILES_ARGUMENTS,
+        ALL_GIT_UNTRACKED_FILES_ARGUMENTS,
+    ):
+        changed_path_bytes = _run_git_bytes(repository_path, each_arguments)
+        if changed_path_bytes is None:
+            return None
+        all_path_bytes.update(
+            each_path_bytes
+            for each_path_bytes in changed_path_bytes.split(GIT_PATH_SEPARATOR)
+            if each_path_bytes
+        )
+    return tuple(sorted(all_path_bytes))
+
+
+def _add_digest_record(input_digest: hashlib._Hash, record_bytes: bytes) -> None:
+    input_digest.update(
+        len(record_bytes).to_bytes(
+            DIGEST_LENGTH_BYTES,
+            byteorder=DIGEST_BYTE_ORDER,
+        )
+    )
+    input_digest.update(record_bytes)
+
+
+def _read_input_bytes(input_path: Path) -> bytes | None:
+    try:
+        return input_path.read_bytes()
+    except OSError:
+        return None

package/scripts/local_verification/manifest.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from collections.abc import Mapping
+from pathlib import Path, PurePosixPath, PureWindowsPath
+
+from .config import (
+    ALL_MANIFEST_DIGEST_SEPARATORS,
+    CHECK_ARGUMENTS_KEY,
+    CHECK_DIRECTORY_KEY,
+    CHECK_ID_KEY,
+    CHECK_MINIMUM_TESTS_KEY,
+    CHECK_TIMEOUT_KEY,
+    EXCLUSION_REASON_KEY,
+    EXCLUSION_SELECTOR_KEY,
+    MANIFEST_CHECKS_KEY,
+    MANIFEST_DIGEST_ALGORITHM,
+    MANIFEST_EXCLUSIONS_KEY,
+    MANIFEST_VERSION,
+    MANIFEST_VERSION_KEY,
+    UTF8_ENCODING,
+)
+from .model import CheckSpec, ExclusionSpec, VerificationManifest
+
+
+class ManifestRunFatal(ValueError):
+    """Raised when a verification manifest does not follow version 1."""
+
+
+def compute_manifest_digest(manifest: VerificationManifest) -> str:
+    """Return a stable digest for the validated manifest structure.
+
+    Args:
+        manifest: Validated required-check manifest.
+
+    Returns:
+        A SHA-256 digest that covers every executed manifest field.
+    """
+    canonical_manifest = json.dumps(
+        _manifest_mapping(manifest),
+        sort_keys=True,
+        separators=ALL_MANIFEST_DIGEST_SEPARATORS,
+    )
+    return hashlib.new(
+        MANIFEST_DIGEST_ALGORITHM, canonical_manifest.encode(UTF8_ENCODING)
+    ).hexdigest()
+
+
+def _manifest_mapping(manifest: VerificationManifest) -> dict[str, object]:
+    all_check_mappings = [
+        {
+            CHECK_ID_KEY: each_check.check_id,
+            CHECK_ARGUMENTS_KEY: list(each_check.command_arguments),
+            CHECK_DIRECTORY_KEY: each_check.cwd,
+            CHECK_TIMEOUT_KEY: each_check.timeout_seconds,
+            CHECK_MINIMUM_TESTS_KEY: each_check.minimum_tests,
+        }
+        for each_check in manifest.checks
+    ]
+    all_exclusion_mappings = [
+        {
+            EXCLUSION_SELECTOR_KEY: each_exclusion.selector,
+            EXCLUSION_REASON_KEY: each_exclusion.reason,
+        }
+        for each_exclusion in manifest.exclusions
+    ]
+    return {
+        MANIFEST_VERSION_KEY: manifest.version,
+        MANIFEST_CHECKS_KEY: all_check_mappings,
+        MANIFEST_EXCLUSIONS_KEY: all_exclusion_mappings,
+    }
+
+
+def load_manifest(manifest_path: Path) -> VerificationManifest:
+    """Read and validate a required-check manifest.
+
+    Args:
+        manifest_path: JSON file containing the required checks.
+
+    Returns:
+        The validated manifest.
+
+    Raises:
+        ManifestRunFatal: If the file cannot describe a valid manifest.
+        OSError: If the file cannot be read.
+    """
+    try:
+        parsed_manifest: object = json.loads(
+            manifest_path.read_text(encoding=UTF8_ENCODING)
+        )
+    except json.JSONDecodeError as error:
+        raise ManifestRunFatal(f"Manifest is not valid JSON: {error}") from error
+    manifest_mapping = _require_mapping(parsed_manifest, "manifest")
+    manifest_version = _require_integer(manifest_mapping, "version", "manifest")
+    if manifest_version != MANIFEST_VERSION:
+        raise ManifestRunFatal(f"Manifest version must be {MANIFEST_VERSION}")
+    all_checks = _load_checks(manifest_mapping.get("checks"))
+    all_exclusions = _load_exclusions(manifest_mapping.get("exclusions", []))
+    return VerificationManifest(
+        manifest_version, tuple(all_checks), tuple(all_exclusions)
+    )
+
+
+def _load_checks(raw_checks: object) -> list[CheckSpec]:
+    if not isinstance(raw_checks, list) or not raw_checks:
+        raise ManifestRunFatal("Manifest checks must be a non-empty array")
+    all_checks: list[CheckSpec] = []
+    all_check_ids: set[str] = set()
+    for each_index, each_raw_check in enumerate(raw_checks):
+        all_check_fields = _require_mapping(each_raw_check, f"checks[{each_index}]")
+        check_spec = _load_check(all_check_fields, each_index)
+        if check_spec.check_id in all_check_ids:
+            raise ManifestRunFatal("Check ids must be unique")
+        all_check_ids.add(check_spec.check_id)
+        all_checks.append(check_spec)
+    return all_checks
+
+
+def _load_check(all_check_fields: Mapping[str, object], check_index: int) -> CheckSpec:
+    location = f"checks[{check_index}]"
+    check_id = _require_text(all_check_fields, "id", location)
+    all_command_arguments = _load_command_arguments(
+        all_check_fields.get("argv"), location
+    )
+    cwd = _load_relative_directory(all_check_fields.get("cwd"), location)
+    timeout_seconds = _load_timeout(all_check_fields.get("timeout_seconds"), location)
+    minimum_tests = _load_minimum_tests(all_check_fields.get("minimum_tests"), location)
+    return CheckSpec(
+        check_id, all_command_arguments, cwd, timeout_seconds, minimum_tests
+    )
+
+
+def _load_command_arguments(raw_arguments: object, location: str) -> tuple[str, ...]:
+    if not isinstance(raw_arguments, list) or not raw_arguments:
+        raise ManifestRunFatal(f"{location}.argv must be a non-empty array")
+    if any(
+        not isinstance(each_argument, str) or not each_argument
+        for each_argument in raw_arguments
+    ):
+        raise ManifestRunFatal(f"{location}.argv must contain non-empty strings")
+    return tuple(raw_arguments)
+
+
+def _load_exclusions(raw_exclusions: object) -> list[ExclusionSpec]:
+    if not isinstance(raw_exclusions, list):
+        raise ManifestRunFatal("Manifest exclusions must be an array")
+    all_exclusions: list[ExclusionSpec] = []
+    for each_index, each_raw_exclusion in enumerate(raw_exclusions):
+        all_exclusion_fields = _require_mapping(
+            each_raw_exclusion, f"exclusions[{each_index}]"
+        )
+        location = f"exclusions[{each_index}]"
+        selector = _require_text(all_exclusion_fields, "selector", location)
+        reason = _require_text(all_exclusion_fields, "reason", location)
+        all_exclusions.append(ExclusionSpec(selector, reason))
+    return all_exclusions
+
+
+def _load_relative_directory(raw_directory: object, location: str) -> str:
+    if not isinstance(raw_directory, str) or not raw_directory:
+        raise ManifestRunFatal(f"{location}.cwd must be a repo-relative directory")
+    return _validate_relative_directory(raw_directory, location)
+
+
+def _validate_relative_directory(directory_text: str, location: str) -> str:
+    normalized_directory = directory_text.replace("\\", "/")
+    directory_path = PurePosixPath(normalized_directory)
+    if (
+        directory_path.is_absolute()
+        or normalized_directory.startswith("/")
+        or PureWindowsPath(normalized_directory).drive
+        or any(each_part == ".." for each_part in directory_path.parts)
+    ):
+        raise ManifestRunFatal(f"{location}.cwd must stay inside the repository")
+    return directory_path.as_posix()
+
+
+def _load_timeout(raw_timeout: object, location: str) -> float:
+    if isinstance(raw_timeout, bool) or not isinstance(raw_timeout, (int, float)):
+        raise ManifestRunFatal(f"{location}.timeout_seconds must be positive")
+    timeout_seconds = float(raw_timeout)
+    if not math.isfinite(timeout_seconds) or timeout_seconds <= 0:
+        raise ManifestRunFatal(f"{location}.timeout_seconds must be positive")
+    return timeout_seconds
+
+
+def _load_minimum_tests(raw_minimum: object, location: str) -> int | None:
+    if raw_minimum is None:
+        return None
+    if (
+        isinstance(raw_minimum, bool)
+        or not isinstance(raw_minimum, int)
+        or raw_minimum < 0
+    ):
+        raise ManifestRunFatal(
+            f"{location}.minimum_tests must be a non-negative integer"
+        )
+    return raw_minimum
+
+
+def _require_mapping(candidate: object, location: str) -> Mapping[str, object]:
+    if not isinstance(candidate, Mapping):
+        raise ManifestRunFatal(f"{location} must be an object")
+    return candidate
+
+
+def _require_text(
+    all_fields: Mapping[str, object], field_name: str, location: str
+) -> str:
+    field_text = all_fields.get(field_name)
+    if not isinstance(field_text, str) or not field_text.strip():
+        raise ManifestRunFatal(f"{location}.{field_name} must be a non-empty string")
+    return field_text
+
+
+def _require_integer(
+    all_fields: Mapping[str, object], field_name: str, location: str
+) -> int:
+    field_number = all_fields.get(field_name)
+    if isinstance(field_number, bool) or not isinstance(field_number, int):
+        raise ManifestRunFatal(f"{location}.{field_name} must be an integer")
+    return field_number

package/scripts/local_verification/model.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TypeAlias
+
+from .config import (
+    CHECK_FAILED_EXIT_CODE,
+    FAILED_STATUS,
+    INCOMPLETE_EXIT_CODE,
+    INCOMPLETE_STATUS,
+    PASSED_STATUS,
+    SUCCESS_EXIT_CODE,
+)
+
+CheckStatus: TypeAlias = str
+AggregateStatus: TypeAlias = str
+
+
+@dataclass(frozen=True)
+class CheckSpec:
+    check_id: str
+    command_arguments: tuple[str, ...]
+    cwd: str
+    timeout_seconds: float
+    minimum_tests: int | None = None
+
+
+@dataclass(frozen=True)
+class ExclusionSpec:
+    selector: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class VerificationManifest:
+    version: int
+    checks: tuple[CheckSpec, ...]
+    exclusions: tuple[ExclusionSpec, ...]
+
+
+@dataclass(frozen=True)
+class CommandCapture:
+    exit_code: int | None
+    stdout_text: str
+    stderr_text: str
+    error_kind: str | None
+    error_message: str | None
+
+
+@dataclass(frozen=True)
+class CheckLogPaths:
+    stdout: Path
+    stderr: Path
+    collection_stdout: Path
+    collection_stderr: Path
+
+
+@dataclass(frozen=True)
+class CheckRecord:
+    check_id: str
+    status: CheckStatus
+    command_arguments: tuple[str, ...]
+    cwd: str
+    exit_code: int | None
+    duration_seconds: float
+    stdout_log: Path
+    stderr_log: Path
+    error_kind: str | None = None
+    error_message: str | None = None
+    minimum_tests: int | None = None
+    collected_tests: int | None = None
+    collection_exit_code: int | None = None
+
+    def as_dict(self) -> dict[str, object]:
+        """Return the JSON record for this check.
+
+        Returns:
+            A JSON-compatible check record using the manifest argv key.
+        """
+        return {
+            "id": self.check_id,
+            "status": self.status,
+            "argv": list(self.command_arguments),
+            "cwd": self.cwd,
+            "exit_code": self.exit_code,
+            "duration_seconds": self.duration_seconds,
+            "stdout_log": str(self.stdout_log),
+            "stderr_log": str(self.stderr_log),
+            "error_kind": self.error_kind,
+            "error_message": self.error_message,
+            "minimum_tests": self.minimum_tests,
+            "collected_tests": self.collected_tests,
+            "collection_exit_code": self.collection_exit_code,
+        }
+
+
+@dataclass(frozen=True)
+class VerificationReport:
+    version: int
+    repository: Path
+    base_revision: str | None
+    checks: tuple[CheckRecord, ...]
+    exclusions: tuple[ExclusionSpec, ...]
+    head_revision: str | None = None
+    manifest_digest: str = ""
+    is_worktree_clean: bool = False
+    is_inputs_unchanged: bool = False
+    is_publishable: bool = False
+
+    @property
+    def worktree_clean(self) -> bool:
+        return self.is_worktree_clean
+
+    @property
+    def inputs_unchanged(self) -> bool:
+        return self.is_inputs_unchanged
+
+    @property
+    def publishable(self) -> bool:
+        return self.is_publishable
+
+    @property
+    def aggregate_status(self) -> AggregateStatus:
+        if any(each_record.status == FAILED_STATUS for each_record in self.checks):
+            return FAILED_STATUS
+        if any(each_record.status == INCOMPLETE_STATUS for each_record in self.checks):
+            return INCOMPLETE_STATUS
+        return PASSED_STATUS
+
+    @property
+    def exit_code(self) -> int:
+        if self.aggregate_status == FAILED_STATUS:
+            return CHECK_FAILED_EXIT_CODE
+        if self.aggregate_status == INCOMPLETE_STATUS:
+            return INCOMPLETE_EXIT_CODE
+        return SUCCESS_EXIT_CODE
+
+    def _aggregate_fields(self, all_statuses: list[str]) -> dict[str, object]:
+        return {
+            "status": self.aggregate_status,
+            "total": len(self.checks),
+            "passed": all_statuses.count(PASSED_STATUS),
+            "failed": all_statuses.count(FAILED_STATUS),
+            "incomplete": all_statuses.count(INCOMPLETE_STATUS),
+            "exit_code": self.exit_code,
+        }
+
+    def as_dict(self) -> dict[str, object]:
+        """Return the JSON report for this verification run.
+
+        Returns:
+            A JSON-compatible report with aggregate check counts.
+        """
+        all_statuses = [each_record.status for each_record in self.checks]
+        return {
+            "version": self.version,
+            "schema_version": self.version,
+            "repository": str(self.repository),
+            "head": self.head_revision,
+            "base": self.base_revision,
+            "manifest_digest": self.manifest_digest,
+            "worktree_clean": self.is_worktree_clean,
+            "inputs_unchanged": self.is_inputs_unchanged,
+            "publishable": self.is_publishable,
+            "checks": [each_record.as_dict() for each_record in self.checks],
+            "exclusions": [
+                {"selector": each_exclusion.selector, "reason": each_exclusion.reason}
+                for each_exclusion in self.exclusions
+            ],
+            "aggregate": self._aggregate_fields(all_statuses),
+            "status": self.aggregate_status,
+            "exit_code": self.exit_code,
+        }