report.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/testing/report.py
 
 
# OCT-LINT: disable=no_hardcoded_secrets reason="Section-12.4 requires the 9xxx extension-code catalog to be documented here; catalog doc strings and the module docstring are prose, not credentials"
"""
Report-layer constants and pure mappings for the §20 stand-in (Plan 184).
 
Purpose
-------
Pin everything the spec-10 section 11 and section 20.3 report
contract fixes at the data level: the ``oct-test/v0.4`` schema stamp,
the pinned ``supported_features`` values VERBATIM, the required-field
path list, the documented 9xxx implementation-code catalog (section
12.4 requires the implementation to document its extension codes in
its own catalog — this module IS that catalog), and the section-4
exit-code precedence.
 
Responsibilities
----------------
- ``SCHEMA_STAMP`` / ``SUPPORTED_FEATURES`` / ``REQUIRED_FIELD_PATHS``.
- ``IMPLEMENTATION_ERROR_CODES`` — every 9xxx code the stand-in emits.
- ``make_error`` / ``make_violation`` — the §11 pinned entry shapes.
- ``compute_exit_and_status`` — §4 precedence (4 over 3 over 2 over 1
  over 0) with the §12.3 interrupted-status carve-out.
 
Diagnostics
-----------
Domain: OC_TESTING
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- ``supported_features`` values are the §20.3 pinned set verbatim; a
  serial stand-in reports ``workers_auto: "deferred"``. Since Plan 240
  the stand-in can also DISTRIBUTE, and ADR-T-11's v0.3 amendment
  (readiness audit A-19) makes that one value run-dependent —
  ``"deferred"`` when serial, ``"enforced"`` when the run resolved
  ``auto`` and distributed. This constant stays the SERIAL baseline;
  ``runner._features_for`` applies the parallel value per run, so the
  pinned dict below is still exactly what a serial report carries.
- Timeout counts drive the ``failed`` status class (§11 status rule):
  ``failed`` exactly when ``summary.failed + summary.timeout > 0``.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
"""
from __future__ import annotations
 
from oc_diagnostics import _dbg
 
#: §20.3: the stand-in emits the CURRENT report shape and its stamp.
SCHEMA_STAMP: str = "oct-test/v0.4"
 
#: §20.3 pinned stand-in values, VERBATIM (readiness audit A-19).
SUPPORTED_FEATURES: dict[str, str] = {
    "cwd_chdir": "enforced",
    "env_mutation": "enforced",
    "owned_writes_outside_tmp": "advisory",
    "singleton_reset": "deferred",
    "lock_target_outside_tmp": "deferred",
    "network_marker": "deferred",
    "large_suite_pagination": "deferred",
    "workers_auto": "deferred",
    "error_code_catalog": "enforced",
    "signal_handling": "enforced",
    "per_test_timeout": "enforced",
    "single_package_walk": "enforced",
}
 
#: The §20.3 output subset spelled out as leaf paths (v0.4.2 text).
#: The schema-shape acceptance test pins its own independent copy.
REQUIRED_FIELD_PATHS: tuple[str, ...] = (
    "schema",
    "run_id",
    "status",
    "exit_code",
    "workspace.root",
    "workspace.mode",
    "selection.packages",
    "selection.profile",
    "selection.marker",
    "selection.seed",
    "selection.nodeids",
    "selection.pytest_args",
    "workers.requested",
    "workers.actual",
    "workers.dist_mode",
    "summary",
    "tests",
    "contract_violations",
    "artifacts.junit_xml",
    "artifacts.ndjson",
    "artifacts.ndjson_stream",
    "errors",
    "supported_features",
)
 
#: §12.4 implementation-specific extension codes — the stand-in's own
#: catalog. Consumers MUST tolerate unknown 9xxx codes; these are ours.
IMPLEMENTATION_ERROR_CODES: dict[str, str] = {
    # OCT-LINT: disable=no_hardcoded_secrets reason="Section-12.4 requires the 9xxx extension-code catalog to be documented here; catalog doc strings and the module docstring are prose, not credentials"
    "9001": ("WORKERS_INVALID — the --workers value is neither a positive "
             "integer nor the token 'auto' (section 12.7 reserves invalid "
             "worker counts for a documented 9xxx code)."),
    "9002": ("STANDIN_INTERNAL_ERROR — an unexpected exception escaped the "
             "stand-in orchestrator; the exception class and message are "
             "carried in the error message."),
    # OCT-LINT: disable=no_hardcoded_secrets reason="Section-12.4 requires the 9xxx extension-code catalog to be documented here; catalog doc strings and the module docstring are prose, not credentials"
    "9003": ("STANDIN_UNSUPPORTED_FLAG — a flag that exists in the section-4 "
             "v1.0 grammar (--workspace, --ndjson) is not supported by the "
             "section-20 stand-in; exit 4, configuration class (section "
             "20.1: --workspace rejection is never exit 2)."),
    "9004": ("SEED_INVALID — the --seed value is not an integer."),
    # OCT-LINT: disable=no_hardcoded_secrets reason="Section-12.4 requires the 9xxx extension-code catalog to be documented here; catalog doc strings and the module docstring are prose, not credentials"
    "9005": ("PER_TEST_TIMEOUT_INVALID — the --per-test-timeout value is "
             "not a positive integer number of seconds."),
    # OCT-LINT: disable=no_hardcoded_secrets reason="Section-12.4 requires the 9xxx extension-code catalog to be documented here; catalog doc strings and the module docstring are prose, not credentials"
    "9006": ("OUTPUT_TESTS_LIMIT_INVALID — the --output-tests-limit value "
             "is not a positive integer (the flag itself is otherwise "
             "accepted and ignored per the section-20.3 no-sink rule)."),
    # OCT-LINT: disable=no_hardcoded_secrets reason="Section-12.4 requires the 9xxx extension-code catalog to be documented here; catalog doc strings and the module docstring are prose, not credentials"
    "9007": ("WORKERS_CLAMPED — the requested --workers count exceeded the "
             "workspace manifest's max_workers cap for this package and was "
             "clamped to it; the run continued at the cap. Warning "
             "severity: the run is valid, it simply used fewer workers "
             "than asked for (Plan 240 P2)."),
    "9008": ("PYTEST_UNEXPECTED_EXIT — the in-process pytest run returned "
             "an exit class the stand-in did not produce itself (internal "
             "error or usage error); the pytest exit code is in the "
             "message."),
}
 
#: Top-level status enum (§11).
STATUSES: tuple[str, ...] = (
    "passed", "failed", "contract_violation", "orchestrator_error",
    "orchestrator_interrupted", "configuration_error",
)
 
 
def make_error(
    kind: str,
    code: str,
    severity: str,
    message: str,
    source: str = "orchestrator",
) -> dict:
    """Build a §11 ``errors[]`` entry ``{kind, code, severity, message,
    source}``."""
    func = "make_error"
    _dbg("OC_TESTING", func, f"{kind}/{code}/{severity}", 4)
    return {
        "kind": kind,
        "code": code,
        "severity": severity,
        "message": message,
        "source": source,
    }
 
 
def make_violation(
    rule_id: str,
    file: str,
    nodeid: str | None,
    severity: str,
    message: str,
) -> dict:
    """Build a §11 ``contract_violations[]`` entry ``{rule_id, file,
    nodeid, severity, message}`` (nodeid ``None`` for file/run-level
    findings)."""
    func = "make_violation"
    _dbg("OC_TESTING", func, f"{rule_id}@{file}", 4)
    return {
        "rule_id": rule_id,
        "file": file,
        "nodeid": nodeid,
        "severity": severity,
        "message": message,
    }
 
 
def compute_exit_and_status(
    *,
    fatal_config: bool,
    interrupted: bool,
    orchestrator_error: bool,
    error_violations: bool,
    failed_or_timeout: bool,
) -> tuple[int, str]:
    """§4 exit precedence: 4 over 3 over 2 over 1 over 0.
 
    ``interrupted`` and ``orchestrator_error`` share exit 3; the
    interrupted STATUS wins when both hold (§12.6: an
    ``ORCHESTRATOR_INTERRUPTED`` signal already forced exit 3).
    """
    func = "compute_exit_and_status"
    if fatal_config:
        result = (4, "configuration_error")
    elif interrupted:
        result = (3, "orchestrator_interrupted")
    elif orchestrator_error:
        result = (3, "orchestrator_error")
    elif error_violations:
        result = (2, "contract_violation")
    elif failed_or_timeout:
        result = (1, "failed")
    else:
        result = (0, "passed")
    _dbg("OC_TESTING", func, f"-> {result}", 4)
    return result
 
 
_dbg("OC_TESTING", "module", "loaded", 4)
 
__all__ = [
    "SCHEMA_STAMP",
    "SUPPORTED_FEATURES",
    "REQUIRED_FIELD_PATHS",
    "IMPLEMENTATION_ERROR_CODES",
    "STATUSES",
    "make_error",
    "make_violation",
    "compute_exit_and_status",
]