cli.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/testing/cli.py
 
"""
The §20.1 argv contract for the stand-in (Plan 184).
 
Purpose
-------
Parse exactly the stand-in grammar: the eight §20.1 flags plus
``--per-test-timeout`` (ADR-T-07) plus accepted-but-ignored
``--output-tests-limit`` (§20.3 no-sink rule). Anything else — unknown
flags, bare positionals, a literal ``--`` (ADR-T-16), or the
v1.0-grammar flags the stand-in does not support (``--workspace``,
``--ndjson``) — produces an exit-4-class configuration error with the
right catalog code.
 
Responsibilities
----------------
- ``parse_argv`` — pure argv → (config, errors); first error wins.
- ``StandInConfig`` — the parsed invocation.
 
Diagnostics
-----------
Domain: OC_TESTING
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- No prefix abbreviation: tokens match the grammar exactly.
- Both ``--flag value`` and ``--flag=value`` forms are accepted.
- ``parse_argv`` performs no filesystem or environment access.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.testing.report (error constructors)
"""
from __future__ import annotations
 
from dataclasses import dataclass, field
 
from oc_diagnostics import _dbg
 
from oc_chat.testing.report import make_error
 
_PROFILES = ("strict", "smoke", "full")
 
#: Flags that take a value.
_VALUE_FLAGS = {
    "--package", "--profile", "--seed", "--workers", "--marker",
    "--nodeid", "--per-test-timeout", "--output-tests-limit", "--ndjson",
}
#: Flags that take no value.
_BARE_FLAGS = {"--dry-run", "--json", "--workspace"}
 
 
@dataclass
class StandInConfig:
    """The parsed §20.1 stand-in invocation."""
 
    package: str | None = None
    profile: str = "strict"
    profile_explicit: bool = False
    seed: int | None = None
    workers: int | str = "auto"
    marker: str | None = None
    nodeids: list[str] = field(default_factory=list)
    per_test_timeout: int | None = None
    output_tests_limit: int | None = None
    dry_run: bool = False
    json_out: bool = False
 
 
def _fatal(code: str, message: str) -> list[dict]:
    return [make_error("configuration", code, "fatal", message)]
 
 
def parse_argv(argv: list[str]) -> tuple[StandInConfig | None, list[dict]]:
    """Parse *argv* against the stand-in grammar.
 
    Returns ``(config, [])`` on success or ``(None, [error])`` with a
    single fatal configuration error (first error wins; nothing runs).
    """
    func = "parse_argv"
    _dbg("OC_TESTING", func, f"argv={argv}", 3)
 
    if "--" in argv:
        return None, _fatal(
            "UNSUPPORTED_ARGUMENT",
            "a literal '--' (pytest passthrough) is outside the grammar; "
            "the surface accepts no pytest passthrough (ADR-T-16)",
        )
 
    cfg = StandInConfig()
    i = 0
    while i < len(argv):
        token = argv[i]
        name, eq, inline_value = token.partition("=")
        if name in _BARE_FLAGS:
            if eq:
                return None, _fatal(
                    "UNSUPPORTED_ARGUMENT",
                    f"flag {name} takes no value (got {token!r})",
                )
            value: str | None = None
        elif name in _VALUE_FLAGS:
            if eq:
                value = inline_value
            else:
                if i + 1 >= len(argv):
                    return None, _fatal(
                        "UNSUPPORTED_ARGUMENT",
                        f"flag {name} requires a value",
                    )
                i += 1
                value = argv[i]
        else:
            return None, _fatal(
                "UNSUPPORTED_ARGUMENT",
                f"unrecognized argument {token!r}: the stand-in accepts "
                "only the section-20.1 grammar",
            )
 
        if name == "--workspace":
            return None, _fatal(
                "9003",
                "--workspace is rejected with exit code 4 until workspace "
                "mode exists (section 20.1); use --package oc_chat",
            )
        if name == "--ndjson":
            return None, _fatal(
                "9003",
                "the ndjson flag belongs to the full grammar; the stand-in "
                "implements no ndjson sink (section 20.3) and rejects it",
            )
        if name == "--dry-run":
            cfg.dry_run = True
        elif name == "--json":
            cfg.json_out = True
        elif name == "--package":
            cfg.package = value
        elif name == "--profile":
            if value not in _PROFILES:
                return None, _fatal(
                    "PROFILE_INVALID",
                    f"--profile {value!r} is not one of strict, smoke, full",
                )
            cfg.profile = str(value)
            cfg.profile_explicit = True
        elif name == "--seed":
            try:
                cfg.seed = int(str(value), 10)
            except ValueError:
                return None, _fatal(
                    "9004", f"--seed {value!r} is not an integer",
                )
        elif name == "--workers":
            if value == "auto":
                cfg.workers = "auto"
            else:
                try:
                    count = int(str(value), 10)
                except ValueError:
                    count = 0
                if count < 1:
                    return None, _fatal(
                        "9001",
                        f"--workers {value!r} is neither a positive integer "
                        "nor 'auto'",
                    )
                cfg.workers = count
        elif name == "--marker":
            cfg.marker = str(value)
        elif name == "--nodeid":
            cfg.nodeids.append(str(value))
        elif name == "--per-test-timeout":
            try:
                seconds = int(str(value), 10)
            except ValueError:
                seconds = 0
            if seconds < 1:
                return None, _fatal(
                    "9005",
                    f"--per-test-timeout {value!r} is not a positive "
                    "integer number of seconds",
                )
            cfg.per_test_timeout = seconds
        elif name == "--output-tests-limit":
            try:
                limit = int(str(value), 10)
            except ValueError:
                limit = 0
            if limit < 1:
                return None, _fatal(
                    "9006",
                    f"--output-tests-limit {value!r} is not a positive "
                    "integer",
                )
            cfg.output_tests_limit = limit
        i += 1
 
    _dbg("OC_TESTING", func, f"parsed profile={cfg.profile} "
         f"workers={cfg.workers} nodeids={len(cfg.nodeids)}", 3)
    return cfg, []
 
 
_dbg("OC_TESTING", "module", "loaded", 4)
 
__all__ = ["StandInConfig", "parse_argv"]