claude-dev-env 8.6.1 → 8.8.0

package/scripts/dev_env_scripts_constants/review_closure_constants.py

@@ -0,0 +1,241 @@
+"""Constants for the review_closure script.
+
+Per the project's configuration conventions, script-level scalar constants
+live in dev_env_scripts_constants alongside timing.py.
+"""
+
+GITHUB_API_ROOT: str = "https://api.github.com"
+"""Root of the GitHub REST API."""
+
+GITHUB_GRAPHQL_ENDPOINT: str = "https://api.github.com/graphql"
+"""Endpoint that answers the review-thread query."""
+
+PULL_REQUEST_ENDPOINT_TEMPLATE: str = "{api_root}/repos/{slug}/pulls/{number}"
+"""REST route carrying one pull request."""
+
+REVIEW_THREADS_ENDPOINT_TEMPLATE: str = (
+    "{api_root}/repos/{slug}/pulls/{number}/ccr/review_threads"
+)
+"""REST route a Claude Code session has for review threads."""
+
+CHECK_RUNS_ENDPOINT_TEMPLATE: str = (
+    "{api_root}/repos/{slug}/commits/{sha}/check-runs?per_page={page_size}"
+)
+"""REST route carrying the check runs reported on one commit."""
+
+REVIEW_THREAD_PAGE_SIZE: int = 100
+"""How many review threads and comments one query asks for."""
+
+CHECK_RUN_PAGE_SIZE: int = 100
+"""How many check runs one request asks for."""
+
+REVIEW_THREAD_QUERY: str = """
+query($owner: String!, $name: String!, $number: Int!, $pageSize: Int!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      reviewThreads(first: $pageSize) {
+        nodes {
+          path
+          isResolved
+          isOutdated
+          comments(first: $pageSize) {
+            nodes {
+              body
+              author { login }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+"""
+"""GraphQL query for the review threads on one pull request."""
+
+ALL_THREAD_NODE_KEYS: tuple[str, ...] = (
+    "data",
+    "repository",
+    "pullRequest",
+    "reviewThreads",
+    "nodes",
+)
+"""Path from the GraphQL answer down to the review-thread list."""
+
+ALL_RESOLVED_KEYS: tuple[str, ...] = ("isResolved", "resolved", "is_resolved")
+"""Field names either route uses for a resolved review thread."""
+
+ALL_OUTDATED_KEYS: tuple[str, ...] = ("isOutdated", "outdated", "is_outdated")
+"""Field names either route uses for a thread whose code has been replaced."""
+
+ALL_COMMENT_LIST_KEYS: tuple[str, ...] = ("comments", "all_comments")
+"""Field names either route uses for a thread's comment list."""
+
+COMMENT_NODES_KEY: str = "nodes"
+"""GraphQL wraps a comment list in this field."""
+
+COMMENT_BODY_KEY: str = "body"
+"""Field carrying a comment's text."""
+
+ALL_COMMENT_AUTHOR_KEYS: tuple[str, ...] = ("author", "user")
+"""Field names either route uses for a comment's author."""
+
+AUTHOR_LOGIN_KEY: str = "login"
+"""Field carrying an author's GitHub login."""
+
+THREAD_PATH_KEY: str = "path"
+"""Field carrying the file a review thread points at."""
+
+UNNAMED_THREAD_SUBJECT: str = "a review thread"
+"""Subject text for a thread that names no file."""
+
+RED_CIRCLE_MARKER: str = "\U0001f534"
+"""The red circle a review marks a blocking finding with."""
+
+APPROVALS_CHECK_NAME: str = "Claude Approvals"
+"""Name of the check run whose rows carry blocking findings."""
+
+ALL_BLOCKING_CONCLUSIONS: tuple[str, ...] = ("failure", "action_required")
+"""Check-run conclusions that mean a blocking row is open on this head."""
+
+APPROVALS_OPEN_REASON: str = (
+    "the Claude Approvals check reports a blocking row on this commit"
+)
+"""Why a failing approvals check leaves the pull request open."""
+
+RED_CIRCLE_OPEN_REASON: str = (
+    "a blocking finding here carries no reply from the driving agent"
+)
+"""Why a red-circle thread stays open until the agent answers it."""
+
+UNANSWERED_OPEN_REASON: str = "unresolved, with no reply from the driving agent"
+"""Why an ordinary thread stays open."""
+
+CHECK_RUNS_KEY: str = "check_runs"
+"""Field carrying the check-run list in the REST answer."""
+
+CHECK_RUN_NAME_KEY: str = "name"
+"""Field carrying a check run's name."""
+
+CHECK_RUN_CONCLUSION_KEY: str = "conclusion"
+"""Field carrying a check run's conclusion."""
+
+HEAD_KEY: str = "head"
+"""Field carrying a pull request's head."""
+
+SHA_KEY: str = "sha"
+"""Field carrying a commit identifier."""
+
+NUMBER_KEY: str = "number"
+"""Field carrying a pull request number."""
+
+USER_KEY: str = "user"
+"""Field carrying the account that opened a pull request."""
+
+SHORT_SHA_LENGTH: int = 7
+"""How much of a commit identifier the verdict line prints."""
+
+SLUG_SEPARATOR: str = "/"
+"""Separator between owner and name in a repository slug."""
+
+QUERY_KEY: str = "query"
+"""GraphQL payload field carrying the query text."""
+
+VARIABLES_KEY: str = "variables"
+"""GraphQL payload field carrying the query variables."""
+
+OWNER_VARIABLE: str = "owner"
+"""GraphQL variable naming the repository owner."""
+
+NAME_VARIABLE: str = "name"
+"""GraphQL variable naming the repository."""
+
+NUMBER_VARIABLE: str = "number"
+"""GraphQL variable naming the pull request number."""
+
+PAGE_SIZE_VARIABLE: str = "pageSize"
+"""GraphQL variable naming the page size."""
+
+ALL_TOKEN_ENVIRONMENT_VARIABLES: tuple[str, ...] = (
+    "GITHUB_TOKEN",
+    "GH_TOKEN",
+)
+"""Environment variables that carry a GitHub token, in the order read."""
+
+NO_SIGN_IN_MESSAGE: str = (
+    "No GitHub token found. Set GITHUB_TOKEN or GH_TOKEN and run this again."
+)
+"""What to print when no token is available."""
+
+COMMAND_DESCRIPTION: str = (
+    "Report whether every review finding on a pull request head has been "
+    "answered by the agent driving it."
+)
+"""Help text for the command."""
+
+SLUG_ARGUMENT_HELP: str = "Repository as owner/name."
+"""Help text for the repository argument."""
+
+NUMBER_ARGUMENT_HELP: str = "Pull request number."
+"""Help text for the pull request argument."""
+
+DRIVER_LOGIN_ARGUMENT_HELP: str = (
+    "A login whose comments count as the driving agent's reply. Repeatable. "
+    "The account that opened the pull request always counts."
+)
+"""Help text for the driver login argument."""
+
+CLOSED_VERDICT_LABEL: str = "CLOSED"
+"""Verdict label for a pull request with every finding answered."""
+
+OPEN_VERDICT_LABEL: str = "OPEN"
+"""Verdict label for a pull request with a finding still waiting."""
+
+CLOSED_DETAIL: str = "every review finding on this commit is answered"
+"""Detail text on a closed verdict."""
+
+OPEN_DETAIL_TEMPLATE: str = "{count} review finding(s) wait on the driving agent"
+"""Detail text on an open verdict."""
+
+VERDICT_LINE_TEMPLATE: str = "{label} {slug}#{number} {sha} :: {detail}"
+"""Shape of the one verdict line this command prints."""
+
+FINDING_LINE_TEMPLATE: str = "  - {subject}: {reason}"
+"""Shape of each open-finding line printed under the verdict."""
+
+CLOSED_EXIT_CODE: int = 0
+"""Exit status when every finding is answered."""
+
+OPEN_EXIT_CODE: int = 1
+"""Exit status when a finding waits on the driving agent."""
+
+ERROR_EXIT_CODE: int = 2
+"""Exit status when the pull request state could not be read."""
+
+REQUEST_TIMEOUT_SECONDS: int = 30
+"""How long one GitHub request waits for an answer."""
+
+REQUEST_FAILED_TEMPLATE: str = "{url} answered {status}"
+"""What to report when GitHub answers with something other than success."""
+
+GET_METHOD: str = "GET"
+"""HTTP method for a read."""
+
+POST_METHOD: str = "POST"
+"""HTTP method the GraphQL query uses."""
+
+COMMENT_IDS_KEY: str = "comment_ids"
+"""Field the session route uses for a thread's comment identifiers."""
+
+COMMENT_IDENTIFIER_KEY: str = "id"
+"""Field carrying a review comment's identifier."""
+
+REVIEW_COMMENTS_ENDPOINT_TEMPLATE: str = (
+    "{api_root}/repos/{slug}/pulls/{number}/comments?per_page={page_size}&page={page}"
+)
+"""REST route carrying one page of a pull request's review comments."""
+
+REVIEW_COMMENT_PAGE_SIZE: int = 100
+"""How many review comments one page carries."""
+
+MAX_REVIEW_COMMENT_PAGES: int = 20
+"""How many comment pages one run reads before it stops."""

package/scripts/dev_env_scripts_constants/test_claude_account_constants.py

@@ -0,0 +1,21 @@
+"""The second-account thresholds keep the main account the protected one."""
+
+from __future__ import annotations
+
+from dev_env_scripts_constants.claude_account_constants import (
+    LAUNCHER_TEXT_TEMPLATE,
+    MAIN_SESSION_USED_CEILING_PERCENT,
+    MAIN_WEEKLY_USED_CEILING_PERCENT,
+    SECOND_SESSION_USED_CEILING_PERCENT,
+    SECOND_WEEKLY_USED_CEILING_PERCENT,
+)
+
+
+def test_main_ceilings_sit_below_the_second_account_ceilings() -> None:
+    assert MAIN_WEEKLY_USED_CEILING_PERCENT < SECOND_WEEKLY_USED_CEILING_PERCENT
+    assert MAIN_SESSION_USED_CEILING_PERCENT < SECOND_SESSION_USED_CEILING_PERCENT
+
+
+def test_launcher_names_the_profile_and_passes_every_argument() -> None:
+    assert "{profile_home}" in LAUNCHER_TEXT_TEMPLATE
+    assert "claude %*" in LAUNCHER_TEXT_TEMPLATE

package/scripts/dev_env_scripts_constants/test_code_review_constants.py

@@ -0,0 +1,12 @@
+"""Behavioral tests for the host-aware code-review invoker constants module."""
+
+from __future__ import annotations
+
+from dev_env_scripts_constants import code_review_constants as review_constants
+
+
+def test_default_effort_is_a_known_token() -> None:
+    assert (
+        review_constants.DEFAULT_CODE_REVIEW_EFFORT
+        in review_constants.ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER
+    )

package/scripts/dev_env_scripts_constants/test_contrast_framing_constants.py

@@ -0,0 +1,60 @@
+"""The contrast-framing form list stays usable by both linters."""
+
+from __future__ import annotations
+
+from dev_env_scripts_constants.contrast_framing_constants import (
+    ALL_CONTRAST_FRAMING_FORMS,
+    CONTRAST_FRAMING_MESSAGE_TEMPLATE,
+)
+
+
+def test_every_form_carries_a_distinct_name() -> None:
+    all_names = [each_form.name for each_form in ALL_CONTRAST_FRAMING_FORMS]
+
+    assert len(set(all_names)) == len(all_names)
+
+
+def test_no_form_matches_prose_that_states_what_is() -> None:
+    all_clean_lines = (
+        "The function runs more than 30 lines.",
+        "The reader reads more than 30 lines a minute.",
+        "The check names the failing line and the fix.",
+        "Push the branch and read the verdict.",
+        "Three attempts, then park the member.",
+    )
+    for each_form in ALL_CONTRAST_FRAMING_FORMS:
+        for each_line in all_clean_lines:
+            assert each_form.pattern.search(each_line) is None
+
+
+def test_every_pattern_reports_the_words_that_carry_the_contrast() -> None:
+    all_expected_matches = {
+        "trailing-comma-not": (", not s", "a diff regression, not shared code"),
+        "corrective-it-is-not": (
+            "it is not a flake, it is",
+            "it is not a flake, it is a bug",
+        ),
+        "substitution-rather-than": ("rather than", "park it rather than fix it"),
+        "additive-not-just": ("not just", "not just for today"),
+        "comparative-ranking": (
+            "matters more than",
+            "precision matters more than coverage",
+        ),
+        "substitution-as-opposed-to": (
+            "as opposed to",
+            "a warning as opposed to a failure",
+        ),
+    }
+    for each_form in ALL_CONTRAST_FRAMING_FORMS:
+        expected_text, example_line = all_expected_matches[each_form.name]
+        assert each_form.pattern.search(example_line).group(0) == expected_text
+
+
+def test_the_message_template_carries_the_three_parts() -> None:
+    message = CONTRAST_FRAMING_MESSAGE_TEMPLATE.format(
+        name="trailing-comma-not", text="a fix, not a workaround", guidance="State it."
+    )
+
+    assert "trailing-comma-not" in message
+    assert "a fix, not a workaround" in message
+    assert message.endswith("State it.")

package/scripts/durable_post_lint.py

@@ -8,6 +8,10 @@ from collections.abc import Sequence
 from dataclasses import dataclass
 from pathlib import Path
 
+from contrast_framing import describe_contrast_framing, find_contrast_framing
+from dev_env_scripts_constants.contrast_framing_constants import (
+    CONTRAST_FRAMING_FINDING_CODE,
+)
 from durable_post_lint_config.config.constants import (
     ACTION_PR_CREATE,
     ACTION_PR_EDIT,
@@ -134,10 +138,30 @@ def _description_heading_findings(body_text: str) -> list[DurablePostFinding]:
     ]
 
 
+def _contrast_framing_findings(text: str) -> list[DurablePostFinding]:
+    all_lines = text.splitlines()
+    return [
+        DurablePostFinding(
+            code=CONTRAST_FRAMING_FINDING_CODE,
+            message=describe_contrast_framing(
+                all_lines[each_line_number - 1], each_form_name
+            ),
+        )
+        for each_line_number, _each_column, each_form_name in find_contrast_framing(
+            text
+        )
+    ]
+
+
 def _title_findings(title: str | None) -> list[DurablePostFinding]:
-    if title is None or CONVENTIONAL_TITLE_PATTERN.fullmatch(title) is not None:
+    if title is None:
         return []
-    return [DurablePostFinding(code=INVALID_TITLE_CODE, message=INVALID_TITLE_MESSAGE)]
+    all_findings = _contrast_framing_findings(title)
+    if CONVENTIONAL_TITLE_PATTERN.fullmatch(title) is None:
+        all_findings.append(
+            DurablePostFinding(code=INVALID_TITLE_CODE, message=INVALID_TITLE_MESSAGE)
+        )
+    return all_findings
 
 
 def _is_release_automation_branch(head_branch: str | None) -> bool:
@@ -172,8 +196,10 @@ def _body_findings(
         )
     if _is_release_automation_branch(head_branch):
         all_findings.extend(_release_body_findings(body_text))
-    elif action in ALL_PR_DESCRIPTION_ACTIONS:
-        all_findings.extend(_description_heading_findings(body_text))
+    else:
+        if action in ALL_PR_DESCRIPTION_ACTIONS:
+            all_findings.extend(_description_heading_findings(body_text))
+        all_findings.extend(_contrast_framing_findings(body_text))
     if find_volatile_path_marker(body_text) is not None:
         all_findings.append(
             DurablePostFinding(

package/scripts/followup_cli.py

@@ -281,21 +281,17 @@ def _run_count(repository_root: Path, stdout: TextIO) -> int:
         and BACKLOG_EXCEEDED_EXIT_CODE once it passes it.
     """
     finding_count = len(all_recorded_findings(repository_root))
-    if finding_count <= FOLLOWUP_BACKLOG_THRESHOLD:
-        stdout.write(
-            BACKLOG_WITHIN_TEMPLATE.format(
-                finding_count=finding_count, threshold=FOLLOWUP_BACKLOG_THRESHOLD
-            )
-            + LINE_SEPARATOR
-        )
-        return SUCCESS_EXIT_CODE
+    within_threshold = finding_count <= FOLLOWUP_BACKLOG_THRESHOLD
+    finding_template = (
+        BACKLOG_WITHIN_TEMPLATE if within_threshold else BACKLOG_EXCEEDED_TEMPLATE
+    )
     stdout.write(
-        BACKLOG_EXCEEDED_TEMPLATE.format(
+        finding_template.format(
             finding_count=finding_count, threshold=FOLLOWUP_BACKLOG_THRESHOLD
         )
         + LINE_SEPARATOR
     )
-    return BACKLOG_EXCEEDED_EXIT_CODE
+    return SUCCESS_EXIT_CODE if within_threshold else BACKLOG_EXCEEDED_EXIT_CODE
 
 
 def _run_clear(repository_root: Path) -> int:

package/scripts/merge_gate_checks.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""Hold a merge policy document to the branch ruleset it describes.
+
+A policy document names the checks a pull request passes before it merges.
+Those names go stale the moment the branch ruleset stops requiring one of
+them, and the document then promises a gate that never runs.
+
+The document carries one fenced block whose info string is
+``required-status-checks``. Each line inside it is one check context, spelled
+the way the ruleset spells it.
+
+::
+
+    ```required-status-checks
+    instruction-pairs / instruction-pairs
+    ```
+    ok:   the ruleset requires that context      -> exit 0
+    flag: the ruleset dropped that context       -> exit 1, one line naming it
+
+The ruleset arrives two ways. A checked-in snapshot keeps the comparison
+offline, which is what the paired test suite reads. ``--live`` reads the
+ruleset from the GitHub API, and ``--refresh`` writes the live answer back to
+the snapshot file.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.request
+from collections.abc import Iterator, Sequence
+from pathlib import Path
+from typing import TextIO
+
+from dev_env_scripts_constants.merge_gate_check_constants import (
+    ALL_GITHUB_TOKEN_VARIABLES,
+    FENCE_MARKER,
+    JSON_INDENT_WIDTH,
+    MERGE_GATE_CLEAN_EXIT_CODE,
+    MERGE_GATE_MISSING_CHECK_EXIT_CODE,
+    REQUIRED_CHECK_BLOCK_INFO_STRING,
+    REQUIRED_STATUS_CHECKS_RULE_TYPE,
+    RULE_CONTEXT_KEY,
+    RULE_PARAMETERS_KEY,
+    RULE_TYPE_KEY,
+    RULESET_API_ACCEPT_HEADER,
+    RULESET_API_TEMPLATE,
+    RULESET_REQUEST_TIMEOUT_SECONDS,
+    UTF8_ENCODING,
+)
+
+
+def parse_declared_contexts(document_text: str) -> list[str]:
+    """Read the check contexts a policy document declares, in document order.
+
+    ::
+
+        parse_declared_contexts("```required-status-checks\\nRuff\\n```\\n")
+        ok: ["Ruff"]
+
+    A document with no such block declares nothing.
+
+    Args:
+        document_text: The whole policy document.
+
+    Returns:
+        The contexts inside the ``required-status-checks`` block, in the order
+        the document lists them, and an empty list when the block is absent.
+    """
+    all_stripped_lines = [each_line.strip() for each_line in document_text.splitlines()]
+    opening_fence = FENCE_MARKER + REQUIRED_CHECK_BLOCK_INFO_STRING
+    if opening_fence not in all_stripped_lines:
+        return []
+    block_body_index = all_stripped_lines.index(opening_fence) + 1
+    all_declared_contexts: list[str] = []
+    for each_line in all_stripped_lines[block_body_index:]:
+        if each_line == FENCE_MARKER:
+            break
+        if each_line:
+            all_declared_contexts.append(each_line)
+    return all_declared_contexts
+
+
+def ruleset_contexts(ruleset_payload: object) -> set[str]:
+    """Read every status-check context a branch ruleset requires.
+
+    A rule of another type carries no context and is passed over.
+
+    Args:
+        ruleset_payload: The list of rules the branch-rules endpoint returns.
+
+    Returns:
+        Every context named by a ``required_status_checks`` rule.
+    """
+    all_required_contexts: set[str] = set()
+    for each_rule in _required_status_check_rules(ruleset_payload):
+        all_required_contexts.update(_rule_contexts(each_rule))
+    return all_required_contexts
+
+
+def missing_contexts(document_text: str, ruleset_payload: object) -> list[str]:
+    """Name the declared contexts the ruleset stopped requiring.
+
+    An empty list means the ruleset requires every check the document names,
+    so the document's promise holds.
+
+    Args:
+        document_text: The whole policy document.
+        ruleset_payload: The list of rules the branch-rules endpoint returns.
+
+    Returns:
+        The declared contexts the ruleset leaves out, in document order.
+    """
+    all_required_contexts = ruleset_contexts(ruleset_payload)
+    return [
+        each_context
+        for each_context in parse_declared_contexts(document_text)
+        if each_context not in all_required_contexts
+    ]
+
+
+def main(all_arguments: Sequence[str]) -> int:
+    """Compare the document against the snapshot, or against the live ruleset.
+
+    Args:
+        all_arguments: The command-line arguments after the program name.
+
+    Returns:
+        ``0`` when the ruleset requires every declared context, and ``1`` with
+        one line per context the ruleset leaves out.
+    """
+    parser = _build_parser()
+    parsed_arguments = parser.parse_args(all_arguments)
+    wants_live_ruleset = parsed_arguments.live or parsed_arguments.refresh
+    if wants_live_ruleset and not parsed_arguments.repository:
+        parser.error("--live and --refresh need --repository")
+    ruleset_payload = _resolve_ruleset(parsed_arguments)
+    document_text = parsed_arguments.document.read_text(encoding=UTF8_ENCODING)
+    return _report_missing(
+        parsed_arguments.document,
+        missing_contexts(document_text, ruleset_payload),
+        sys.stdout,
+    )
+
+
+def _required_status_check_rules(
+    ruleset_payload: object,
+) -> Iterator[dict[str, object]]:
+    if not isinstance(ruleset_payload, list):
+        return
+    for each_rule in ruleset_payload:
+        if isinstance(each_rule, dict) and (
+            each_rule.get(RULE_TYPE_KEY) == REQUIRED_STATUS_CHECKS_RULE_TYPE
+        ):
+            yield each_rule
+
+
+def _rule_contexts(all_rule_fields: dict[str, object]) -> set[str]:
+    parameters = all_rule_fields.get(RULE_PARAMETERS_KEY)
+    if not isinstance(parameters, dict):
+        return set()
+    all_declared_checks = parameters.get(REQUIRED_STATUS_CHECKS_RULE_TYPE)
+    if not isinstance(all_declared_checks, list):
+        return set()
+    return {
+        each_check[RULE_CONTEXT_KEY]
+        for each_check in all_declared_checks
+        if isinstance(each_check, dict)
+        and isinstance(each_check.get(RULE_CONTEXT_KEY), str)
+    }
+
+
+def _read_github_token() -> str | None:
+    for each_variable_name in ALL_GITHUB_TOKEN_VARIABLES:
+        token = os.environ.get(each_variable_name)
+        if token:
+            return token
+    return None
+
+
+def _fetch_ruleset(repository: str, branch: str) -> object:
+    request = urllib.request.Request(
+        RULESET_API_TEMPLATE.format(repository=repository, branch=branch),
+        headers={"Accept": RULESET_API_ACCEPT_HEADER},
+    )
+    token = _read_github_token()
+    if token:
+        request.add_header("Authorization", f"Bearer {token}")
+    with urllib.request.urlopen(
+        request, timeout=RULESET_REQUEST_TIMEOUT_SECONDS
+    ) as api_reply:
+        return json.loads(api_reply.read().decode(UTF8_ENCODING))
+
+
+def _resolve_ruleset(parsed_arguments: argparse.Namespace) -> object:
+    if not (parsed_arguments.live or parsed_arguments.refresh):
+        return json.loads(parsed_arguments.ruleset.read_text(encoding=UTF8_ENCODING))
+    ruleset_payload = _fetch_ruleset(
+        parsed_arguments.repository, parsed_arguments.branch
+    )
+    if parsed_arguments.refresh:
+        parsed_arguments.ruleset.write_text(
+            json.dumps(ruleset_payload, indent=JSON_INDENT_WIDTH) + "\n",
+            encoding=UTF8_ENCODING,
+        )
+    return ruleset_payload
+
+
+def _report_missing(
+    document_path: Path, all_absent_contexts: Sequence[str], stream: TextIO
+) -> int:
+    if not all_absent_contexts:
+        stream.write(f"{document_path}: the ruleset requires every named check\n")
+        return MERGE_GATE_CLEAN_EXIT_CODE
+    stream.writelines(
+        f"{document_path}: the branch ruleset does not require {each_context!r}\n"
+        for each_context in all_absent_contexts
+    )
+    return MERGE_GATE_MISSING_CHECK_EXIT_CODE
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Check a merge policy document.")
+    parser.add_argument("--document", required=True, type=Path)
+    parser.add_argument("--ruleset", required=True, type=Path)
+    parser.add_argument("--repository")
+    parser.add_argument("--branch", default="main")
+    parser.add_argument("--live", action="store_true")
+    parser.add_argument("--refresh", action="store_true")
+    return parser
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))