test_contract_parity.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/tests_mcp/test_contract_parity.py
 
"""
Purpose
-------
OI-502 / FS-502 — MCP contract parity harness. The validator's
``_TOOL_MODEL_MAP`` and the executor's ``_ARGV_BUILDERS`` must register
the same set of tool names, and each registered tool must be executable
against a realistic validated-args dict without tripping the executor's
``.get()`` defaults into producing a CLI flag that the real ``oct`` CLI
does not accept.
 
The test exercises three invariants:
 
1. **Registry parity** — ``set(_TOOL_MODEL_MAP) == set(_ARGV_BUILDERS)``.
2. **Per-tool argv well-formed** — for every tool, instantiate the model
   with sensible defaults, call its argv builder, and check the first
   four elements match ``[sys.executable, "-m", "oct", <subcommand>]``.
3. **No spurious flags** — for a curated list of previously-drifting
   flags (``--output-dir``, ``--check``, ``--jobs`` on ``oct test``,
   ``--json`` on ``oct diag``) the argv must *not* contain the flag.
   Regression coverage for the bugs this harness was introduced to fix.
 
The harness is intentionally static — it does not spawn the ``oct`` CLI
or compare against ``--help`` output, so it runs fast and works even in
environments where click or pytest are missing.
 
Responsibilities
----------------
- Verify registry parity between ``_TOOL_MODEL_MAP`` and
  ``_ARGV_BUILDERS``.
- Verify per-tool argv starts with
  ``[sys.executable, "-m", "oct", <subcommand>]``.
- Verify previously-drifting flags do not appear in builder output.
 
Diagnostics
-----------
Domain: MCP-TESTS
Levels:
    L2 — test lifecycle
    L3 — assertion details
    L4 — deep tracing
 
Contracts
---------
- The parity test must fail if a new tool is added to one registry and
  not the other.
- The spurious-flag checks must fail if a previously-fixed executor
  regression is re-introduced.
"""
 
from __future__ import annotations
 
import sys
from pathlib import Path
 
import pytest
 
from oct.mcp.executor import _ARGV_BUILDERS
from oct.mcp.validator import _TOOL_MODEL_MAP, validate_tool_args
 
 
#: Minimal (model-valid) args dict per tool. Keys that the executor
#: needs are provided; anything omitted falls back to the model default.
_MINIMAL_ARGS: dict[str, dict] = {
    "oct_lint": {},
    "oct_health": {},
    "oct_skeleton": {},
    "oct_deps": {},
    "oct_test": {},
    "oct_typecheck": {},
    "oct_diag": {},
    "oct_git_status": {},
    "oct_git_check": {},
    "oct_format": {"apply": False, "confirm": False},
    "oct_docs": {},
    "oct_export_source": {},
    "oct_new": {"path": "src/foo.py"},
    "oct_scaffold": {"name": "example"},
    "oct_clean": {},
    "oct_install_hooks": {},
    "oct_git_commit": {"message": "feat(core): add parity test"},
    "oct_git_hooks_install": {},
    "oct_git_init": {},
    "oct_git_changelog": {},
}
 
 
#: Expected CLI subcommand path per tool (first non-sys-executable argv
#: segment after ``-m oct``).
_EXPECTED_SUBCOMMAND: dict[str, list[str]] = {
    "oct_lint": ["lint"],
    "oct_health": ["health"],
    "oct_skeleton": ["export-skeleton"],
    "oct_deps": ["deps"],
    "oct_test": ["test"],
    "oct_typecheck": ["typecheck"],
    "oct_diag": ["diag", "validate-config"],
    "oct_git_status": ["git", "status"],
    "oct_git_check": ["git", "check"],
    "oct_format": ["format"],
    "oct_docs": ["docs"],
    "oct_export_source": ["export-source"],
    "oct_new": ["new"],
    "oct_scaffold": ["scaffold"],
    "oct_clean": ["clean"],
    "oct_install_hooks": ["git", "hooks", "install"],
    "oct_git_commit": ["git", "commit"],
    "oct_git_hooks_install": ["git", "hooks", "install"],
    "oct_git_init": ["git", "init"],
    "oct_git_changelog": ["git", "changelog"],
}
 
 
def test_registry_parity():
    """Every validator model must have a matching executor argv builder."""
    model_names = set(_TOOL_MODEL_MAP)
    builder_names = set(_ARGV_BUILDERS)
    assert model_names == builder_names, (
        f"Validator/executor drift: "
        f"only in validator={model_names - builder_names!r}, "
        f"only in executor={builder_names - model_names!r}"
    )
 
 
def test_minimal_args_covers_all_tools():
    """_MINIMAL_ARGS must cover every registered tool."""
    assert set(_MINIMAL_ARGS) == set(_TOOL_MODEL_MAP), (
        "Update _MINIMAL_ARGS to mirror validator._TOOL_MODEL_MAP"
    )
 
 
@pytest.mark.parametrize("tool_name", sorted(_TOOL_MODEL_MAP))
def test_model_validates_minimal_args(tool_name: str, tmp_path: Path):
    """Minimal args dict must validate against the registered model."""
    raw = _MINIMAL_ARGS[tool_name]
    model = validate_tool_args(tool_name, raw, project_root=tmp_path)
    assert model is not None
 
 
@pytest.mark.parametrize("tool_name", sorted(_TOOL_MODEL_MAP))
def test_argv_starts_with_expected_subcommand(tool_name: str, tmp_path: Path):
    """Builder output must begin with python -m oct <subcommand>."""
    raw = _MINIMAL_ARGS[tool_name]
    model = validate_tool_args(tool_name, raw, project_root=tmp_path)
    cmd = _ARGV_BUILDERS[tool_name](model.model_dump(), tmp_path)
 
    assert cmd[0] == sys.executable
    assert cmd[1] == "-m"
    assert cmd[2] == "oct"
 
    expected_tail = _EXPECTED_SUBCOMMAND[tool_name]
    assert cmd[3 : 3 + len(expected_tail)] == expected_tail, (
        f"{tool_name}: expected subcommand tail {expected_tail!r}, "
        f"got {cmd[3 : 3 + len(expected_tail)]!r} (full cmd={cmd!r})"
    )
 
 
# ---------------------------------------------------------------------
# Regression guards for previously-drifting flags.
# ---------------------------------------------------------------------
 
 
def _build_cmd(tool_name: str, tmp_path: Path) -> list[str]:
    model = validate_tool_args(
        tool_name, _MINIMAL_ARGS[tool_name], project_root=tmp_path
    )
    return _ARGV_BUILDERS[tool_name](model.model_dump(), tmp_path)
 
 
def test_skeleton_does_not_emit_output_dir(tmp_path: Path):
    """OI-502: CLI ``oct export-skeleton`` does not accept ``--output-dir``."""
    cmd = _build_cmd("oct_skeleton", tmp_path)
    assert "--output-dir" not in cmd
 
 
def test_deps_does_not_emit_check(tmp_path: Path):
    """OI-502: CLI ``oct deps`` does not accept ``--check``."""
    cmd = _build_cmd("oct_deps", tmp_path)
    assert "--check" not in cmd
 
 
def test_test_does_not_emit_jobs(tmp_path: Path):
    """OI-502: CLI ``oct test`` does not accept ``--jobs``."""
    cmd = _build_cmd("oct_test", tmp_path)
    assert "--jobs" not in cmd
 
 
def test_diag_does_not_emit_json(tmp_path: Path):
    """OI-502: no ``oct diag`` subcommand accepts ``--json`` (yet)."""
    cmd = _build_cmd("oct_diag", tmp_path)
    assert "--json" not in cmd
 
 
def test_format_does_not_emit_jobs(tmp_path: Path):
    """OI-502: ``oct format`` argparser does not register ``--jobs``."""
    cmd = _build_cmd("oct_format", tmp_path)
    assert "--jobs" not in cmd
 
 
# ---------------------------------------------------------------------
# Headline behaviour: scoped + breaking Conventional Commits validate.
# ---------------------------------------------------------------------
 
 
@pytest.mark.parametrize(
    "message",
    [
        "feat(core): add parity harness",
        "fix(mcp): close OI-502",
        "feat!: drop legacy config",
        "refactor(git)!: rename internal helper",
    ],
)
def test_git_commit_accepts_valid_conventional_messages(
    message: str, tmp_path: Path,
):
    """OI-502 / FS-502 — scoped and breaking commits must round-trip."""
    model = validate_tool_args(
        "oct_git_commit", {"message": message}, project_root=tmp_path,
    )
    assert model.message == message
    cmd = _ARGV_BUILDERS["oct_git_commit"](model.model_dump(), tmp_path)
    # git commit receives the message as a single argv element, never
    # via a shell.
    assert message in cmd
    assert "-m" in cmd