claude-dev-env 7.0.0 → 7.2.0

package/scripts/automatic_advisory/cli.py

@@ -0,0 +1,334 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+from collections.abc import Callable, Sequence
+from dataclasses import asdict
+from pathlib import Path
+from typing import TextIO
+
+scripts_directory = Path(__file__).resolve().parents[1]
+if str(scripts_directory) not in sys.path:
+    sys.path.insert(0, str(scripts_directory))
+
+from pr_verification.config.constants import INCOMPLETE_EXIT_CODE, SUCCESS_EXIT_CODE
+from pr_verification.github import GitHubAppAuthenticator
+from pr_verification.lock import SupervisorLock, SupervisorLockError
+from pr_verification.model import RepositorySettings
+
+from automatic_advisory.config.constants import (
+    POLL_ERROR_KEY,
+    POLL_ERROR_LOG_LINE_LIMIT,
+    REPORT_NEWLINE,
+    STATE_FILE_SUFFIX,
+    STATE_STATUS_KEY,
+    STATE_STATUS_NEVER_RUN,
+    UTF8_ENCODING,
+)
+from automatic_advisory.configuration import (
+    AdvisoryConfigurationError,
+    load_advisory_settings,
+)
+from automatic_advisory.model import AdvisorySettings, AdvisoryState
+from automatic_advisory.runner import (
+    AdvisoryGitHub,
+    AutomaticAdvisoryRunner,
+)
+from automatic_advisory.window_flags import detached_poller_creation_flags
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the automatic advisory command parser.
+
+    Returns:
+        Parser for status, one-shot, and polling modes.
+    """
+    parser = argparse.ArgumentParser(prog="cde automatic-advisory")
+    parser.add_argument("--settings", type=Path, required=True)
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--once", action="store_true")
+    mode.add_argument("--poll", action="store_true")
+    mode.add_argument("--status", action="store_true")
+    mode.add_argument("--start", action="store_true")
+    parser.add_argument("--rerun", action="store_true")
+    return parser
+
+
+def main(
+    all_arguments: Sequence[str],
+    *,
+    stdout: TextIO = sys.stdout,
+    stderr: TextIO = sys.stderr,
+    sleeper: Callable[[float], None] = time.sleep,
+) -> int:
+    """Run the selected automatic advisory command.
+
+    Args:
+        all_arguments: Command arguments after the executable name.
+        stdout: Stream for state output.
+        stderr: Stream for configuration and runtime errors.
+        sleeper: Delay function used by polling mode.
+
+    Returns:
+        Zero for a completed command or three for an incomplete run.
+    """
+    return _run_main_command(all_arguments, stdout, stderr, sleeper)
+
+
+def _run_main_command(
+    all_arguments: Sequence[str],
+    stdout: TextIO,
+    stderr: TextIO,
+    sleeper: Callable[[float], None],
+) -> int:
+    try:
+        parsed_arguments, settings = _load_command_inputs(all_arguments)
+        return _run_selected_mode(parsed_arguments, settings, stdout, sleeper)
+    except (AdvisoryConfigurationError, OSError, SupervisorLockError) as error:
+        stderr.write(f"{error}{REPORT_NEWLINE}")
+        return INCOMPLETE_EXIT_CODE
+
+
+def _load_command_inputs(
+    all_arguments: Sequence[str],
+) -> tuple[argparse.Namespace, AdvisorySettings]:
+    parsed_arguments = build_parser().parse_args(list(all_arguments))
+    return parsed_arguments, load_advisory_settings(parsed_arguments.settings)
+
+
+def _run_selected_mode(
+    parsed_arguments: argparse.Namespace,
+    settings: AdvisorySettings,
+    stdout: TextIO,
+    sleeper: Callable[[float], None],
+) -> int:
+    if parsed_arguments.status:
+        write_status(settings, stdout)
+        return SUCCESS_EXIT_CODE
+    if parsed_arguments.start:
+        return start_polling(parsed_arguments.settings)
+    advisory_runner = _build_runner(settings)
+    if parsed_arguments.once:
+        write_states(advisory_runner.run_once(parsed_arguments.rerun), stdout)
+        return SUCCESS_EXIT_CODE
+    with SupervisorLock(settings.poll_lock_root):
+        return run_polling(
+            advisory_runner,
+            settings.poll_seconds,
+            stdout,
+            settings.poll_error_log_path,
+            sleeper,
+        )
+
+
+def start_polling(settings_path: Path) -> int:
+    """Start one detached polling process and return without waiting.
+
+    Args:
+        settings_path: JSON settings passed to the detached process.
+
+    Returns:
+        Zero after the child process starts.
+    """
+    process_flags = detached_poller_creation_flags()
+    resolved_settings_path = settings_path.resolve()
+    subprocess.Popen(
+        (
+            sys.executable,
+            str(Path(__file__).resolve()),
+            "--settings",
+            str(resolved_settings_path),
+            "--poll",
+        ),
+        cwd=Path(__file__).resolve().parents[1],
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        creationflags=process_flags,
+        start_new_session=True,
+    )
+    return SUCCESS_EXIT_CODE
+
+
+def _build_runner(
+    settings: AdvisorySettings,
+) -> AutomaticAdvisoryRunner:
+    authenticator = GitHubAppAuthenticator(
+        settings.api_url,
+        settings.app_id,
+        settings.installation_id,
+        settings.private_key_path,
+    )
+    return AutomaticAdvisoryRunner(
+        settings,
+        None,
+        github_factory=lambda repository: _issue_repository_api(
+            authenticator, repository
+        ),
+    )
+
+
+def _issue_repository_api(
+    authenticator: GitHubAppAuthenticator,
+    repository: RepositorySettings,
+) -> AdvisoryGitHub:
+    return authenticator.issue_repository_api(
+        repository,
+        should_write_issue_labels=True,
+    )
+
+
+def run_polling(
+    advisory_runner: AutomaticAdvisoryRunner,
+    poll_seconds: float,
+    stdout: TextIO,
+    poll_error_log_path: Path,
+    sleeper: Callable[[float], None],
+) -> int:
+    """Run advisory checks until the caller interrupts polling.
+
+    A SupervisorLockError or OSError in a cycle writes one poll_error JSON
+    line to stdout and to poll-errors.log, newest 200 lines, then the next
+    cycle runs. A detached poller sends stdout to DEVNULL, so the log file
+    beside the state files is the readable copy.
+
+    Args:
+        advisory_runner: Runner for explicit checkout and pull request pairs.
+        poll_seconds: Delay between completed cycles.
+        stdout: Stream for each persisted state and each failed cycle.
+        poll_error_log_path: Log file receiving each failed cycle line.
+        sleeper: Delay function used between cycles.
+
+    Returns:
+        Zero after a user interrupt.
+    """
+    try:
+        _repeat_poll_cycles(
+            advisory_runner, poll_seconds, stdout, poll_error_log_path, sleeper
+        )
+    except KeyboardInterrupt:
+        return SUCCESS_EXIT_CODE
+
+
+def _repeat_poll_cycles(
+    advisory_runner: AutomaticAdvisoryRunner,
+    poll_seconds: float,
+    stdout: TextIO,
+    poll_error_log_path: Path,
+    sleeper: Callable[[float], None],
+) -> None:
+    while True:
+        _run_one_poll_cycle(advisory_runner, stdout, poll_error_log_path)
+        sleeper(poll_seconds)
+
+
+def _run_one_poll_cycle(
+    advisory_runner: AutomaticAdvisoryRunner,
+    stdout: TextIO,
+    poll_error_log_path: Path,
+) -> None:
+    try:
+        write_states(advisory_runner.run_once(), stdout)
+    except (OSError, SupervisorLockError) as cycle_error:
+        _write_poll_error(cycle_error, stdout, poll_error_log_path)
+
+
+def _write_poll_error(
+    cycle_error: Exception,
+    stdout: TextIO,
+    poll_error_log_path: Path,
+) -> None:
+    error_line = (
+        json.dumps({POLL_ERROR_KEY: str(cycle_error)}, sort_keys=True) + REPORT_NEWLINE
+    )
+    stdout.write(error_line)
+    stdout.flush()
+    _append_poll_error_line(poll_error_log_path, error_line)
+
+
+def _append_poll_error_line(poll_error_log_path: Path, error_line: str) -> None:
+    """Append one failed-cycle JSON line, keeping the newest 200 lines.
+
+    Skip the log on OSError or ValueError. A raise here would stop the poller.
+    The line already reached stdout. Undecodable bytes are replaced on read.
+
+    Args:
+        poll_error_log_path: Log file receiving the line.
+        error_line: JSON error line, newline included.
+    """
+    try:
+        _replace_poll_error_log(poll_error_log_path, error_line)
+    except (OSError, ValueError):
+        return
+
+
+def _replace_poll_error_log(poll_error_log_path: Path, error_line: str) -> None:
+    poll_error_log_path.parent.mkdir(parents=True, exist_ok=True)
+    all_lines = _poll_error_log_lines(poll_error_log_path)
+    all_lines.append(error_line)
+    temporary_log_path = poll_error_log_path.with_name(
+        poll_error_log_path.name + STATE_FILE_SUFFIX
+    )
+    temporary_log_path.write_text(
+        "".join(all_lines[-POLL_ERROR_LOG_LINE_LIMIT:]), encoding=UTF8_ENCODING
+    )
+    os.replace(temporary_log_path, poll_error_log_path)
+
+
+def _poll_error_log_lines(poll_error_log_path: Path) -> list[str]:
+    if not poll_error_log_path.exists():
+        return []
+    return poll_error_log_path.read_text(
+        encoding=UTF8_ENCODING, errors="replace"
+    ).splitlines(keepends=True)
+
+
+def write_states(
+    all_states: tuple[AdvisoryState, ...],
+    stdout: TextIO,
+) -> None:
+    """Write one JSON state line for each registration.
+
+    Args:
+        all_states: Persisted registration states.
+        stdout: Stream receiving each JSON state line.
+    """
+    stdout.writelines(
+        json.dumps(asdict(each_state), sort_keys=True) + REPORT_NEWLINE
+        for each_state in all_states
+    )
+    stdout.flush()
+
+
+def write_status(settings: AdvisorySettings, stdout: TextIO) -> None:
+    """Write the latest state or never-run marker for each registration.
+
+    Args:
+        settings: Explicit advisory registrations to inspect.
+        stdout: Stream receiving one JSON record per registration.
+    """
+    for each_registration in settings.registrations:
+        state_path = each_registration.state_path
+        if not state_path.is_file():
+            stdout.write(
+                json.dumps(
+                    {
+                        "repository": each_registration.repository.slug,
+                        "pull_request": each_registration.pull_request_number,
+                        STATE_STATUS_KEY: STATE_STATUS_NEVER_RUN,
+                    },
+                    sort_keys=True,
+                )
+                + REPORT_NEWLINE
+            )
+            continue
+        stdout.write(state_path.read_text(encoding="utf-8"))
+    stdout.flush()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/scripts/automatic_advisory/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration for the automatic advisory runner."""

package/scripts/automatic_advisory/config/constants.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+SETTINGS_VERSION = 1
+SETTINGS_VERSION_KEY = "version"
+SETTINGS_REGISTRATIONS_KEY = "registrations"
+SETTINGS_API_URL_KEY = "api_url"
+SETTINGS_APP_ID_KEY = "app_id"
+SETTINGS_INSTALLATION_ID_KEY = "installation_id"
+SETTINGS_SIGNING_FILE_FIELD = "private_" + "key_path"
+SETTINGS_POLL_SECONDS_KEY = "poll_seconds"
+SETTINGS_CHILD_TIMEOUT_SECONDS_KEY = "child_timeout_seconds"
+REGISTRATION_REPOSITORY_KEY = "repository"
+REGISTRATION_PULL_REQUEST_KEY = "pull_request"
+REGISTRATION_CHECKOUT_KEY = "checkout"
+REGISTRATION_MANIFEST_KEY = "manifest"
+REGISTRATION_REPORT_KEY = "report"
+REGISTRATION_STATE_KEY = "state"
+REGISTRATION_BASE_REF_KEY = "base_ref"
+REGISTRATION_REMOTE_KEY = "remote"
+STATE_VERSION = 1
+STATE_VERSION_KEY = "version"
+STATE_REPOSITORY_KEY = "repository"
+STATE_PULL_REQUEST_KEY = "pull_request"
+STATE_STATUS_KEY = "status"
+STATE_REASON_KEY = "reason"
+STATE_HEAD_SHA_KEY = "head_sha"
+STATE_BASE_SHA_KEY = "base_sha"
+STATE_LAST_POLL_KEY = "last_poll"
+STATE_LAST_RUN_KEY = "last_run"
+STATE_REPORT_KEY = "report"
+STATE_STATUS_WAITING = "waiting"
+STATE_STATUS_OFFLINE = "offline"
+STATE_STATUS_CLOSED = "closed"
+STATE_STATUS_PASSED = "passed"
+STATE_STATUS_FAILED = "failed"
+STATE_STATUS_PENDING = "pending"
+STATE_STATUS_ERROR = "error"
+STATE_STATUS_NEVER_RUN = "never_run"
+POLL_ERROR_KEY = "poll_error"
+POLL_ERROR_LOG_FILE_NAME = "poll-errors.log"
+POLL_ERROR_LOG_LINE_LIMIT = 200
+ALL_TERMINAL_STATUSES = frozenset({STATE_STATUS_PASSED, STATE_STATUS_FAILED})
+STATE_REASON_CHECKOUT_MISMATCH = "checkout does not match the open pull request"
+STATE_REASON_DIRTY_CHECKOUT = "checkout has uncommitted changes"
+STATE_REASON_PULL_REQUEST_CLOSED = "pull request is not open"
+STATE_REASON_GITHUB_UNAVAILABLE = "GitHub is unavailable"
+STATE_REASON_BASE_FETCH_FAILED = "base ref fetch failed"
+STATE_REASON_PUBLISH_FAILED = "report publication failed"
+STATE_REASON_CHILD_INCOMPLETE = "verification child did not produce a report"
+STATE_REASON_UNCHANGED = "unchanged remote head and base"
+GIT_EXECUTABLE = "git"
+GIT_FETCH_ARGUMENT = "fetch"
+GIT_NO_TAGS_FLAG = "--no-tags"
+GIT_TERMINAL_PROMPT_ENVIRONMENT_KEY = "GIT_TERMINAL_PROMPT"
+GIT_PROMPT_DISABLED_VALUE = "0"
+GIT_FORCE_FLAG = "--force"
+ALL_GIT_HEAD_ARGUMENTS = ("rev-parse", "HEAD")
+ALL_GIT_STATUS_ARGUMENTS = ("status", "--porcelain=v1", "--untracked-files=all")
+GIT_BASE_REFSPEC_TEMPLATE = (
+    "+refs/heads/{base_ref}:refs/cde/advisory-base/{pull_request}"
+)
+GIT_REMOTE_BASE_REFSPEC_TEMPLATE = (
+    "+refs/heads/{base_ref}:refs/remotes/{remote_name}/{base_ref}"
+)
+GIT_BASE_REF_TEMPLATE = "refs/cde/advisory-base/{pull_request}"
+LOCAL_VERIFICATION_CLI_FILENAME = "cli.py"
+WINDOWS_PRIORITY_CLASS_ATTRIBUTE = "BELOW_NORMAL_PRIORITY_CLASS"
+WINDOWS_PLATFORM = "win32"
+PYTHON_MODULE_ARGUMENT = "-m"
+WINDOWS_PROCESS_HOST_MODULE = "automatic_advisory.process_host"
+WINDOWS_PROCESS_START_SIGNAL = "1"
+WINDOWS_PROCESS_SET_QUOTA_ACCESS = 0x0100
+WINDOWS_PROCESS_TERMINATE_ACCESS = 0x0001
+WINDOWS_EXTENDED_LIMIT_INFORMATION_CLASS = 9
+WINDOWS_JOB_KILL_ON_CLOSE_LIMIT = 0x2000
+DEFAULT_CLONE_URL_SUFFIX = ".git"
+POLL_LOCK_DIRECTORY_NAME = ".poll-process"
+CREATE_NEW_PROCESS_GROUP_ATTRIBUTE = "CREATE_NEW_PROCESS_GROUP"
+CREATE_NO_WINDOW_ATTRIBUTE = "CREATE_NO_WINDOW"
+CHILD_MANIFEST_FLAG = "--manifest"
+CHILD_REPOSITORY_FLAG = "--repo"
+CHILD_BASE_FLAG = "--base"
+CHILD_EXECUTOR_FLAG = "--executor"
+CHILD_OUTPUT_FLAG = "--output"
+SCOPED_VERIFICATION_SCRIPT_PATH = ".github/ci/local_verify.py"
+PYTHONPATH_ENVIRONMENT_KEY = "PYTHONPATH"
+PYTEST_AUTO_WORKERS_ENVIRONMENT_KEY = "PYTEST_XDIST_AUTO_NUM_WORKERS"
+PYTEST_AUTO_WORKERS_LIMIT = "2"
+STATE_FILE_SUFFIX = ".tmp"
+SELECTED_MANIFEST_SUFFIX = ".selected-manifest.json"
+UTF8_ENCODING = "utf-8"
+REPORT_NEWLINE = "\n"
+JSON_INDENT_SPACES = 2

package/scripts/automatic_advisory/config/timing.py

@@ -0,0 +1,4 @@
+DEFAULT_POLL_SECONDS = 60.0
+DEFAULT_CHILD_TIMEOUT_SECONDS = 1800.0
+GIT_FETCH_TIMEOUT_SECONDS = 30.0
+CHILD_CLEANUP_TIMEOUT_SECONDS = 1.0

package/scripts/automatic_advisory/configuration.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Mapping
+from pathlib import Path, PurePosixPath
+
+from pr_verification.config.constants import GITHUB_API_URL, REPOSITORY_SLUG_PATTERN
+from pr_verification.model import RepositorySettings
+
+from .config.constants import (
+    DEFAULT_CLONE_URL_SUFFIX,
+    REGISTRATION_BASE_REF_KEY,
+    REGISTRATION_CHECKOUT_KEY,
+    REGISTRATION_MANIFEST_KEY,
+    REGISTRATION_PULL_REQUEST_KEY,
+    REGISTRATION_REMOTE_KEY,
+    REGISTRATION_REPORT_KEY,
+    REGISTRATION_REPOSITORY_KEY,
+    REGISTRATION_STATE_KEY,
+    SETTINGS_API_URL_KEY,
+    SETTINGS_APP_ID_KEY,
+    SETTINGS_CHILD_TIMEOUT_SECONDS_KEY,
+    SETTINGS_INSTALLATION_ID_KEY,
+    SETTINGS_POLL_SECONDS_KEY,
+    SETTINGS_REGISTRATIONS_KEY,
+    SETTINGS_SIGNING_FILE_FIELD,
+    SETTINGS_VERSION,
+    SETTINGS_VERSION_KEY,
+)
+from .config.timing import DEFAULT_CHILD_TIMEOUT_SECONDS, DEFAULT_POLL_SECONDS
+from .model import AdvisoryRegistration, AdvisorySettings
+
+
+class AdvisoryConfigurationError(ValueError):
+    """Raised when automatic advisory settings are invalid."""
+
+
+def load_advisory_settings(settings_path: Path) -> AdvisorySettings:
+    """Load and validate the explicit automatic advisory registrations.
+
+    Args:
+        settings_path: JSON file containing the advisory settings.
+
+    Returns:
+        Validated settings for the registered checkout and pull request pairs.
+
+    Raises:
+        AdvisoryConfigurationError: If the file or any registration is invalid.
+    """
+    try:
+        parsed_settings = json.loads(settings_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise AdvisoryConfigurationError(str(error)) from error
+    all_settings = _require_mapping(parsed_settings)
+    _require_version(all_settings)
+    return _build_settings(all_settings)
+
+
+def _build_settings(all_settings: Mapping[str, object]) -> AdvisorySettings:
+    registrations = _load_registrations(all_settings)
+    return AdvisorySettings(
+        _load_api_url(all_settings),
+        _require_positive_integer(all_settings, SETTINGS_APP_ID_KEY),
+        _require_positive_integer(all_settings, SETTINGS_INSTALLATION_ID_KEY),
+        _require_absolute_path(all_settings, SETTINGS_SIGNING_FILE_FIELD),
+        _load_positive_number(
+            all_settings,
+            SETTINGS_POLL_SECONDS_KEY,
+            DEFAULT_POLL_SECONDS,
+        ),
+        _load_positive_number(
+            all_settings,
+            SETTINGS_CHILD_TIMEOUT_SECONDS_KEY,
+            DEFAULT_CHILD_TIMEOUT_SECONDS,
+        ),
+        registrations,
+    )
+
+
+def _load_registrations(
+    all_settings: Mapping[str, object],
+) -> tuple[AdvisoryRegistration, ...]:
+    raw_registrations = all_settings.get(SETTINGS_REGISTRATIONS_KEY)
+    if not isinstance(raw_registrations, list) or not raw_registrations:
+        raise AdvisoryConfigurationError("registrations must be a non-empty array")
+    all_registrations = tuple(
+        _load_registration(each_registration) for each_registration in raw_registrations
+    )
+    all_repositories = tuple(
+        each_registration.repository.slug for each_registration in all_registrations
+    )
+    if len(set(all_repositories)) != len(all_repositories):
+        raise AdvisoryConfigurationError(
+            "each repository can have only one automatic advisory registration"
+        )
+    return all_registrations
+
+
+def _load_registration(raw_registration: object) -> AdvisoryRegistration:
+    registration = _require_mapping(raw_registration)
+    repository_slug = _require_text(registration, REGISTRATION_REPOSITORY_KEY)
+    if REPOSITORY_SLUG_PATTERN.fullmatch(repository_slug) is None:
+        raise AdvisoryConfigurationError("repository must use owner/name")
+    pull_request_number = _require_positive_integer(
+        registration, REGISTRATION_PULL_REQUEST_KEY
+    )
+    checkout_path = _require_absolute_path(registration, REGISTRATION_CHECKOUT_KEY)
+    manifest_path = _require_relative_manifest(registration)
+    report_path = _require_absolute_path(registration, REGISTRATION_REPORT_KEY)
+    state_path = _require_absolute_path(registration, REGISTRATION_STATE_KEY)
+    return AdvisoryRegistration(
+        RepositorySettings(repository_slug, repository_slug + DEFAULT_CLONE_URL_SUFFIX),
+        pull_request_number,
+        checkout_path,
+        manifest_path,
+        report_path,
+        state_path,
+        _require_text(registration, REGISTRATION_BASE_REF_KEY),
+        _require_text(registration, REGISTRATION_REMOTE_KEY),
+    )
+
+
+def _load_api_url(all_settings: Mapping[str, object]) -> str:
+    return _require_text_or_default(
+        all_settings, SETTINGS_API_URL_KEY, GITHUB_API_URL
+    ).rstrip("/")
+
+
+def _load_positive_number(
+    all_settings: Mapping[str, object],
+    field_name: str,
+    default_seconds: float,
+) -> float:
+    raw_number = all_settings.get(field_name, default_seconds)
+    if isinstance(raw_number, bool) or not isinstance(raw_number, (float, int)):
+        raise AdvisoryConfigurationError(f"{field_name} must be positive")
+    if raw_number <= 0 or not math.isfinite(raw_number):
+        raise AdvisoryConfigurationError(f"{field_name} must be positive")
+    return float(raw_number)
+
+
+def _require_mapping(raw_payload: object) -> Mapping[str, object]:
+    if not isinstance(raw_payload, Mapping):
+        raise AdvisoryConfigurationError("settings must be an object")
+    return raw_payload
+
+
+def _require_version(all_settings: Mapping[str, object]) -> None:
+    if all_settings.get(SETTINGS_VERSION_KEY) != SETTINGS_VERSION:
+        raise AdvisoryConfigurationError("settings version is unsupported")
+
+
+def _require_text(all_settings: Mapping[str, object], field_name: str) -> str:
+    field_text = all_settings.get(field_name)
+    if not isinstance(field_text, str) or not field_text.strip():
+        raise AdvisoryConfigurationError(f"{field_name} must be a non-empty string")
+    return field_text
+
+
+def _require_text_or_default(
+    all_settings: Mapping[str, object],
+    field_name: str,
+    default_text: str,
+) -> str:
+    field_text = all_settings.get(field_name, default_text)
+    if not isinstance(field_text, str) or not field_text.strip():
+        raise AdvisoryConfigurationError(f"{field_name} must be a non-empty string")
+    return field_text
+
+
+def _require_positive_integer(
+    all_settings: Mapping[str, object], field_name: str
+) -> int:
+    field_number = all_settings.get(field_name)
+    if isinstance(field_number, bool) or not isinstance(field_number, int):
+        raise AdvisoryConfigurationError(f"{field_name} must be positive")
+    if field_number < 1:
+        raise AdvisoryConfigurationError(f"{field_name} must be positive")
+    return field_number
+
+
+def _require_absolute_path(all_settings: Mapping[str, object], field_name: str) -> Path:
+    configured_path = Path(_require_text(all_settings, field_name))
+    if not configured_path.is_absolute():
+        raise AdvisoryConfigurationError(f"{field_name} must be absolute")
+    return configured_path.resolve()
+
+
+def _require_relative_manifest(
+    all_settings: Mapping[str, object],
+) -> PurePosixPath:
+    manifest_text = _require_text(all_settings, REGISTRATION_MANIFEST_KEY)
+    manifest_path = PurePosixPath(manifest_text.replace("\\", "/"))
+    if manifest_path.is_absolute() or ".." in manifest_path.parts:
+        raise AdvisoryConfigurationError("manifest must stay inside checkout")
+    return manifest_path