__main__.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/testing/__main__.py
 
 
"""
CLI entry for the §20 stand-in: ``python -m oc_chat.testing`` (Plan 184).
 
Purpose
-------
Thin process shell over :func:`oc_chat.testing.runner.run_standin`:
emit the report (JSON to stdout under ``--json``; captured pytest
output plus a compact summary otherwise) and exit with the §4 code.
 
Responsibilities
----------------
- ``main`` — run, emit, return the exit code.
- The §12.4 minimal fatal envelope: when the report itself cannot be
  serialised, emit the fixed-shape substitute and exit 3.
 
Diagnostics
-----------
Domain: OC_TESTING
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- Under ``--json`` stdout carries the report document; human notes for
  fatal configuration errors go to stderr (§4).
- The process exit code always equals ``report["exit_code"]``.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.testing.runner (the orchestrator)
"""
from __future__ import annotations
 
import json
import sys
 
from oc_diagnostics import _dbg
 
from oc_chat.testing.runner import run_standin
 
#: §12.4 minimal fatal envelope (fixed shape; serialisation cannot fail
#: for the reasons the full report's did).
_FATAL_ENVELOPE_PREFIX = (
    # OCT-LINT: disable=no_hardcoded_secrets reason="The section-12.4 minimal fatal envelope is a spec-mandated fixed JSON literal; machine schema text, not a credential"
    '{"schema": "oct-test-fatal/v1", "status": "orchestrator_error", '
    '"exit_code": 3, "errors": [{"kind": "orchestrator", '
    '"code": "REPORT_SERIALIZATION_FAILED", "severity": "fatal", '
    '"message": '
)
_FATAL_ENVELOPE_SUFFIX = ', "source": "orchestrator"}]}'
 
 
def main(argv: list[str] | None = None) -> int:
    """Run the stand-in CLI; return the §4 exit code."""
    func = "main"
    args = list(sys.argv[1:]) if argv is None else list(argv)
    result = run_standin(args)
    report = result.report
    _dbg("OC_TESTING", func,
         f"status={report.get('status')} exit={result.exit_code}", 2)
 
    if "--json" in args:
        try:
            document = json.dumps(report, indent=2)
        except (TypeError, ValueError) as exc:
            message = json.dumps(
                f"report serialisation failed: {exc}"[:2000]
            )
            sys.stdout.write(
                _FATAL_ENVELOPE_PREFIX + message + _FATAL_ENVELOPE_SUFFIX
                + "\n"
            )
            return 3
        sys.stdout.write(document + "\n")
        if report.get("status") == "configuration_error":
            sys.stderr.write(
                "oc_chat.testing: configuration error (exit 4); see the "
                "report's errors[] for the catalog code\n"
            )
        return result.exit_code
 
    if result.captured_output:
        sys.stdout.write(result.captured_output)
    summary = report.get("summary", {})
    sys.stdout.write(
        f"oc_chat.testing stand-in: status={report.get('status')} "
        f"exit={result.exit_code} collected={summary.get('collected', 0)} "
        f"passed={summary.get('passed', 0)} "
        f"failed={summary.get('failed', 0)} "
        f"skipped={summary.get('skipped', 0)} "
        f"timeout={summary.get('timeout', 0)} "
        f"violations={len(report.get('contract_violations', []))}\n"
    )
    for entry in report.get("errors", []):
        sys.stdout.write(
            f"  [{entry['severity']}] {entry['code']}: {entry['message']}\n"
        )
    return result.exit_code
 
 
if __name__ == "__main__":
    sys.exit(main())