command.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/mutation/command.py
 
"""
Purpose
-------
Expose the in-house mutation engine through Click as ``oct mutate``.
 
Responsibilities
----------------
- Parse the target, the test path, the per-mutant timeout, and the output mode.
- Enumerate without running anything under ``--list``.
- Stream progress to stderr so stdout keeps its JSON-only contract.
- Convert a named refusal into a clear CLI error rather than a stack trace.
 
Diagnostics
-----------
Domain: OCT-MUTATION
Levels:
    L2 - command lifecycle
    L3 - option and output details
    L4 - deep tracing
 
Contracts
---------
- ``--tests`` is required for a run; there is no default that would silently
  run a whole suite once per mutant.
- Exit code is 0 whenever the run completes; mutation outcomes do not set exit
  codes in v1, which is report-only and gates nothing.
- Machine-readable stdout contains JSON only.
- ``--list`` writes nothing to the target and starts no subprocess.
 
Dependencies
------------
- click (CLI adapter)
- oct.core.git (repository discovery for stable mutant ids)
- oct.mutation.engine (enumeration)
- oct.mutation.report (rendering)
- oct.mutation.runner (execution and classification)
- oct.mutation.sandbox (named refusals)
"""
 
# OCT-LINT: disable-file=dbg_usage reason="Diagnostics would contaminate the command's JSON-only stdout contract"
# OCT-LINT: disable-file=dbg_import reason="Diagnostics would contaminate the command's JSON-only stdout contract"
 
from __future__ import annotations
 
import json
from pathlib import Path
 
import click
 
from oct.core import git as core_git
from oct.mutation.engine import enumerate_file, relative_id
from oct.mutation.report import render_human, render_list
from oct.mutation.runner import DEFAULT_TIMEOUT_SECONDS, run_mutants
from oct.mutation.sandbox import MutationRefusal
 
 
@click.command(name="mutate")
@click.option(
    "--target",
    required=True,
    type=click.Path(exists=True, dir_okay=False, path_type=Path),
    help="Python file to mutate.",
)
@click.option(
    "--tests",
    default=None,
    type=click.Path(exists=True, path_type=Path),
    help="Test file or directory to run once per mutant (required for a run).",
)
@click.option(
    "--timeout",
    type=click.IntRange(min=1),
    default=DEFAULT_TIMEOUT_SECONDS,
    show_default=True,
    help="Seconds allowed for one test run before the mutant is timed out.",
)
@click.option(
    "--json",
    "json_mode",
    is_flag=True,
    help="Emit the full machine-readable report.",
)
@click.option(
    "--list",
    "list_mode",
    is_flag=True,
    help="Enumerate the mutants without running any tests.",
)
def mutate(
    target: Path,
    tests: Path | None,
    timeout: int,
    json_mode: bool,
    list_mode: bool,
) -> None:
    """Mutate a file and report which mutants the tests fail to notice."""
    root = _id_anchor(target)
    if list_mode:
        _emit_list(target, root, json_mode)
        return
    if tests is None:
        raise click.UsageError(
            "--tests is required for a run: mutation runs the given tests once "
            "per mutant, so there is no default that could be safe to assume."
        )
    try:
        report = run_mutants(
            target=target,
            tests=tests,
            timeout=timeout,
            on_progress=_progress,
        )
    except MutationRefusal as exc:
        raise click.ClickException(str(exc)) from exc
    if json_mode:
        click.echo(json.dumps(report.to_dict(), indent=2, sort_keys=True))
        return
    click.echo(render_human(report))
 
 
def _id_anchor(target: Path) -> Path | None:
    """Return the repository root that mutant ids are relative to, if any.
 
    ``--list`` and a real run must agree on ids, so both anchor on the same
    thing. A target outside any repository still enumerates: only running
    requires a repository, because only running rewrites the file.
    """
    resolved = Path(target).resolve()
    if not core_git.is_git_repo(resolved.parent):
        return None
    try:
        return core_git.get_repo_root(resolved.parent)
    except core_git.GitError:
        return None
 
 
def _emit_list(target: Path, root: Path | None, json_mode: bool) -> None:
    """Write the enumeration for ``--list`` in the requested output mode."""
    relpath = relative_id(target, root)
    try:
        mutants = enumerate_file(target, root=root)
    except SyntaxError as exc:
        raise click.ClickException(f"could not parse {relpath}: {exc}") from exc
    if json_mode:
        payload = {
            "target": relpath,
            "totals": {"mutants": len(mutants)},
            "mutants": [mutant.to_dict() for mutant in mutants],
        }
        click.echo(json.dumps(payload, indent=2, sort_keys=True))
        return
    click.echo(render_list(mutants, relpath))
 
 
def _progress(message: str) -> None:
    """Write one progress line to stderr, keeping stdout free for the report."""
    click.echo(message, err=True)