test_command_flags_introspection.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/tests_cli/test_command_flags_introspection.py
 
"""
Purpose
-------
OI-523 drift-prevention regression — :data:`oct.cli._COMMAND_FLAGS` is a
hand-maintained table of ``(flag, description)`` rows rendered by
:meth:`OctGroup.format_help`. It is easy for a contributor to add a new
``@click.option`` on a command and forget to append the matching row to
``_COMMAND_FLAGS``, leaving ``oct --help`` silently out of date.
 
This test walks every non-hidden Click command / subcommand in the ``oct``
CLI and asserts that each declared :class:`click.Option` appears
somewhere in the command's ``_COMMAND_FLAGS`` entry. Running this test in
CI turns a silent doc drift into a loud unit-test failure.
 
Responsibilities
----------------
- Every top-level Click option on every ``oct`` subcommand is mentioned
  in the ``_COMMAND_FLAGS`` rows.
- Every Click group (``git``, ``diag``) exposes its subcommands in the
  group's ``_COMMAND_FLAGS`` rows.
- Argparse-routed commands (``lint``, ``format``, ``typecheck``) are
  skipped because their flags live in ``argparse``, not Click.
 
Diagnostics
-----------
Domain: CLI-TESTS
Levels:
    L2 — test lifecycle
    L3 — assertion details
    L4 — deep tracing
 
Contracts
---------
- Tests introspect the Click command tree in-process; no subprocess or
  filesystem writes.
- Argparse-routed commands are excluded from the check.
"""
 
from __future__ import annotations
 
import click
import pytest
 
from oct.cli import _COMMAND_FLAGS, cli
 
 
# Commands whose flags live in argparse (``oct lint`` etc. accept
# ``nargs=-1 UNPROCESSED`` and re-parse via argparse). Their flag rows
# are curated manually; there is no Click-level introspection to check
# against, so we exclude them from the drift scan.
_ARGPARSE_ROUTED = {"lint", "format", "typecheck"}
 
 
def _click_option_names(cmd: click.Command) -> list[str]:
    """Return the canonical long-option name for each :class:`Option`."""
    names: list[str] = []
    for param in cmd.params:
        if not isinstance(param, click.Option):
            continue
        # ``param.opts`` holds every declared option spelling (``--json`` /
        # ``-j`` / ``--jobs``); pick the longest one as the canonical name.
        long = max(param.opts, key=len) if param.opts else ""
        if long:
            names.append(long)
    return names
 
 
def _walk_commands(
    group: click.Group, prefix: str = "",
) -> list[tuple[str, click.Command]]:
    """Yield ``(qualified_name, command)`` for every non-hidden command."""
    out: list[tuple[str, click.Command]] = []
    ctx = click.Context(group)
    for name in group.list_commands(ctx):
        sub = group.get_command(ctx, name)
        if sub is None or getattr(sub, "hidden", False):
            continue
        qname = f"{prefix}{name}"
        out.append((qname, sub))
        if isinstance(sub, click.Group):
            out.extend(_walk_commands(sub, prefix=f"{qname} "))
    return out
 
 
def _rendered_for(qname: str) -> str:
    """Join the flag rows for ``qname``, falling back to the parent group.
 
    ``_COMMAND_FLAGS`` keys subgroup subcommands under two conventions:
    ``git`` and ``diag`` either get per-subcommand keys (``git status``)
    or roll the subcommands into the parent key (``diag``). Either
    convention satisfies the drift guard.
    """
    parts = qname.split()
    rows = _COMMAND_FLAGS.get(qname, [])
    if not rows and len(parts) > 1:
        rows = _COMMAND_FLAGS.get(parts[0], [])
    return " | ".join(f"{flag} {desc}" for flag, desc in rows)
 
 
# Commands where the current manual convention rolls subcommand options
# into the parent group entry; the drift guard accepts this as long as
# the parent mentions the option. These are allow-listed here so each
# exception is visible and deliberate rather than permissive by default.
_ROLLED_INTO_PARENT = {
    "diag validate-config",
    "diag list-domains",
    "diag set-level",
    "diag migrate-config",
    "diag restore",
}
 
 
def test_every_click_option_appears_in_command_flags():
    missing: list[tuple[str, str]] = []
    for qname, cmd in _walk_commands(cli):
        if qname in _ARGPARSE_ROUTED:
            continue
        rendered = _rendered_for(qname)
        for option_name in _click_option_names(cmd):
            if option_name in rendered:
                continue
            # diag subcommands may document their flags inline in the
            # ``diag`` parent entry — accept that convention.
            if qname in _ROLLED_INTO_PARENT and option_name in _rendered_for("diag"):
                continue
            missing.append((qname, option_name))
 
    assert not missing, (
        "Drift detected — the following @click.option declarations are "
        "missing from _COMMAND_FLAGS: " + ", ".join(
            f"{q}:{o}" for q, o in missing
        )
    )
 
 
def test_every_group_subcommand_appears_in_group_flags():
    # For each Click group (``git``, ``diag``), every non-hidden
    # subcommand name should appear in the group's _COMMAND_FLAGS entry.
    missing: list[tuple[str, str]] = []
    ctx = click.Context(cli)
    for name in cli.list_commands(ctx):
        sub = cli.get_command(ctx, name)
        if not isinstance(sub, click.Group) or getattr(sub, "hidden", False):
            continue
        rows = _COMMAND_FLAGS.get(name, [])
        rendered = " | ".join(f"{flag} {desc}" for flag, desc in rows)
        sub_ctx = click.Context(sub)
        for sub_name in sub.list_commands(sub_ctx):
            sub_cmd = sub.get_command(sub_ctx, sub_name)
            if sub_cmd is None or getattr(sub_cmd, "hidden", False):
                continue
            if sub_name not in rendered:
                missing.append((name, sub_name))
 
    assert not missing, (
        "Drift detected — the following Click subcommands are missing "
        "from their group's _COMMAND_FLAGS entry: " + ", ".join(
            f"{g}:{s}" for g, s in missing
        )
    )
 
 
def test_command_flags_entries_only_reference_known_commands():
    # Catch typos in _COMMAND_FLAGS keys. Every key must be either a
    # known top-level command or a "<group> <subcommand>" pair.
    ctx = click.Context(cli)
    top_level = set(cli.list_commands(ctx))
    groups = {
        name: cli.get_command(ctx, name)
        for name in top_level
        if isinstance(cli.get_command(ctx, name), click.Group)
    }
 
    stale: list[str] = []
    for key in _COMMAND_FLAGS:
        parts = key.split()
        if len(parts) == 1:
            if parts[0] not in top_level:
                stale.append(key)
        else:
            group_name, sub_name = parts[0], " ".join(parts[1:])
            group = groups.get(group_name)
            if group is None:
                stale.append(key)
                continue
            sub_ctx = click.Context(group)
            if sub_name.split()[0] not in group.list_commands(sub_ctx):
                # Allow nested groups (e.g. "git hooks install").
                nested = group.get_command(sub_ctx, sub_name.split()[0])
                if not isinstance(nested, click.Group):
                    stale.append(key)
 
    assert not stale, (
        "_COMMAND_FLAGS has keys that do not map to real commands: "
        + ", ".join(stale)
    )