errors.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/testing/errors.py
 
# OCT-LINT: disable=no_hardcoded_secrets reason="Operator-approved 2026-08-12: spec-anchor-dense prose trips entropy thresholds (module docstring 5.10 bits/char at L5, 9101 catalog description 4.56 at L118); static documentation strings, no credentials"
"""
Purpose
-------
The spec-10 §12.4 error taxonomy for the ``oct test`` v1.0 seed
(Plan 189) - AS DATA. The library never calls ``sys.exit``; it raises
:class:`OctTestError` carrying the stable §12.4 code, the error kind,
and the severity, plus the kind → exit-code mapping the future v1.0
CLI slice applies at its boundary.
 
Responsibilities
----------------
- Define the §12.4 stable identifiers the discovery layer emits
  (``WORKSPACE_FILE_NOT_FOUND``, ``WORKSPACE_AND_PACKAGE_BOTH_PASSED``,
  ``PACKAGE_UNKNOWN``, ``CWD_RESOLUTION_FAILED``).
- Define and CATALOG the implementation-specific ``9xxx`` extension
  codes this seed uses (§12.4 reserves the range and requires the
  implementation to document its codes; ``IMPLEMENTATION_CODE_CATALOG``
  is that catalog).
- Provide :class:`OctTestError` and its §11 ``errors[]``-entry
  projection, and :func:`exit_code_for_kind` (configuration → 4,
  orchestrator → 3, signal → 3 per §12.3/§12.6/§12.7).
 
Diagnostics
-----------
Domain: OCT-TESTING
Levels:
    L2: lifecycle events (none emitted here - pure data module)
    L3: semantic details (none emitted here)
    L4: deep tracing (none emitted here)
 
Contracts
---------
- NO ``sys.exit`` and no I/O in this module - exits are data the CLI
  maps later (Plan 189 pinned decision).
- Two conditions never share a code (§12.8 house rule): the base
  v0.25 loader rejecting an existing manifest is ``9101``; a
  test-block/test-config content violation is ``9102``.
- Every §12.4 stable identifier is its own value, so consumers can
  compare against these constants or against the spec's literals.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
"""
 
from __future__ import annotations
from oct.core.diagnostics import _dbg
 
 
# ---------------------------------------------------------------------
# Error kinds (§11 ``errors[].kind``) and severities
# ---------------------------------------------------------------------
 
#: Configuration error class (§12.7): catchable before pytest starts.
KIND_CONFIGURATION: str = "configuration"
 
#: Orchestrator error class (§12.6): independent of the test suite.
KIND_ORCHESTRATOR: str = "orchestrator"
 
#: Signal class (§12.3): interrupt/termination handling.
KIND_SIGNAL: str = "signal"
 
#: Fatal severity - the run cannot proceed / the exit code changes.
SEVERITY_FATAL: str = "fatal"
 
#: Warning severity - recorded, the run continues (not used by the
#: discovery layer; part of the shared taxonomy surface).
SEVERITY_WARNING: str = "warning"
 
 
# ---------------------------------------------------------------------
# §12.4 stable identifiers (the discovery-layer subset)
# ---------------------------------------------------------------------
 
#: ``--workspace`` was passed but no ``.option_c_workspace.json``
#: exists in any parent.
WORKSPACE_FILE_NOT_FOUND: str = "WORKSPACE_FILE_NOT_FOUND"
 
#: The mutually exclusive ``--workspace`` and ``--package`` flags were
#: both supplied.
WORKSPACE_AND_PACKAGE_BOTH_PASSED: str = "WORKSPACE_AND_PACKAGE_BOTH_PASSED"
 
#: ``--package P`` was passed but ``P`` is not listed and test-enabled
#: in the workspace file (or does not match the cwd basename in the
#: single-package fallback).
PACKAGE_UNKNOWN: str = "PACKAGE_UNKNOWN"
 
#: Bare invocation walked four parent levels without finding
#: ``pyproject.toml`` or ``pytest.ini`` (ADR-T-12).
CWD_RESOLUTION_FAILED: str = "CWD_RESOLUTION_FAILED"
 
 
# ---------------------------------------------------------------------
# Implementation-specific 9xxx extension codes (§12.4 reserved range)
# ---------------------------------------------------------------------
 
#: The workspace manifest EXISTS but the shipping v0.25 base loader
#: (``oct.core.workspace.load_workspace``) rejects it - wrong
#: ``version``, missing ``name``, malformed subprojects, unreadable
#: JSON. §12.7 pins this condition to the implementation range.
WORKSPACE_MANIFEST_INVALID: str = "9101"
 
#: The base schema is valid but the §9 test configuration is not: a
#: malformed ``test`` block (``enabled`` missing/non-bool, a profile
#: outside strict/smoke/full, missing/empty/absolute/escaping
#: ``test_roots`` on an enabled package) or an invalid top-level
#: ``default_test_profile``.
MANIFEST_TEST_BLOCK_INVALID: str = "9102"
 
#: §12.4: "The implementation MUST document its codes in a sibling
#: artifact (release notes or its own catalog)." This dict is that
#: catalog for the ``oct.testing`` seed.
IMPLEMENTATION_CODE_CATALOG: dict[str, str] = {
    # OCT-LINT: disable=no_hardcoded_secrets reason="Exit-code catalogue prose, not a secret"
    WORKSPACE_MANIFEST_INVALID: (
        "workspace manifest exists but the v0.25 base loader rejects "
        "it (schema/version/name/subprojects/JSON failure)"
    ),
    MANIFEST_TEST_BLOCK_INVALID: (
        "workspace manifest base schema is valid but a §9 test block "
        "or the top-level default_test_profile is invalid"
    ),
}
 
 
# ---------------------------------------------------------------------
# Exit-code mapping (data for the future CLI slice - never applied here)
# ---------------------------------------------------------------------
 
#: Orchestrator errors take exit code 3 (§12.6); signals force 3
#: (§12.3).
EXIT_ORCHESTRATOR_ERROR: int = 3
 
#: Fatal configuration errors take exit code 4 (§12.7).
EXIT_CONFIGURATION_ERROR: int = 4
 
_KIND_TO_EXIT: dict[str, int] = {
    KIND_CONFIGURATION: EXIT_CONFIGURATION_ERROR,
    KIND_ORCHESTRATOR: EXIT_ORCHESTRATOR_ERROR,
    KIND_SIGNAL: EXIT_ORCHESTRATOR_ERROR,
}
 
 
def exit_code_for_kind(kind: str) -> int:
    """Return the §12 exit code for an error *kind*.
 
    Parameters
    ----------
    kind
        One of :data:`KIND_CONFIGURATION`, :data:`KIND_ORCHESTRATOR`,
        :data:`KIND_SIGNAL`.
 
    Returns
    -------
    int
        ``4`` for configuration errors, ``3`` for orchestrator and
        signal errors.
 
    Raises
    ------
    ValueError
        If *kind* is not one of the three taxonomy kinds (a caller
        bug, not a runtime condition - VALIDATION_ERROR class).
    """
    func = "exit_code_for_kind"
    _dbg("OCT-TESTING", func, f"mapping failure kind {kind!r} to an exit code", 4)
    try:
        return _KIND_TO_EXIT[kind]
    except KeyError:
        raise ValueError(
            f"unknown error kind {kind!r}; expected one of "
            f"{sorted(_KIND_TO_EXIT)}",
        ) from None
 
 
class OctTestError(Exception):
    """A spec-10 taxonomy error carried as data (no exit applied).
 
    Attributes
    ----------
    code
        A §12.4 stable identifier or a documented ``9xxx`` code.
    message
        Human-readable condition detail. For ``CWD_RESOLUTION_FAILED``
        this is the ADR-T-12 pinned text, verbatim.
    kind
        §11 error kind; the discovery layer only raises
        :data:`KIND_CONFIGURATION`.
    severity
        §11 severity; discovery errors are always
        :data:`SEVERITY_FATAL`.
    source
        Dotted producer name, or ``"orchestrator"`` when config
        validation itself is the immediate cause (§12.4 population
        rule).
    """
 
    def __init__(
        self,
        code: str,
        message: str,
        *,
        kind: str = KIND_CONFIGURATION,
        severity: str = SEVERITY_FATAL,
        source: str = "orchestrator",
    ) -> None:
        super().__init__(f"{code}: {message}")
        self.code = code
        self.message = message
        self.kind = kind
        self.severity = severity
        self.source = source
 
    @property
    def exit_code(self) -> int:
        """The exit code the CLI slice maps this error to (§12)."""
        return exit_code_for_kind(self.kind)
 
    def to_error_entry(self) -> dict[str, str]:
        """Project this error as a §11 report ``errors[]`` entry."""
        return {
            "kind": self.kind,
            "code": self.code,
            "severity": self.severity,
            "message": self.message,
            "source": self.source,
        }
 
 
__all__ = [
    "CWD_RESOLUTION_FAILED",
    "EXIT_CONFIGURATION_ERROR",
    "EXIT_ORCHESTRATOR_ERROR",
    "IMPLEMENTATION_CODE_CATALOG",
    "KIND_CONFIGURATION",
    "KIND_ORCHESTRATOR",
    "KIND_SIGNAL",
    "MANIFEST_TEST_BLOCK_INVALID",
    "OctTestError",
    "PACKAGE_UNKNOWN",
    "SEVERITY_FATAL",
    "SEVERITY_WARNING",
    "WORKSPACE_AND_PACKAGE_BOTH_PASSED",
    "WORKSPACE_FILE_NOT_FOUND",
    "WORKSPACE_MANIFEST_INVALID",
    "exit_code_for_kind",
]