oct.mutation.command Namespace Reference

Functions
None	mutate (Path target, Path|None tests, int timeout, bool json_mode, bool list_mode)
Path|None	_id_anchor (Path target)
None	_emit_list (Path target, Path|None root, bool json_mode)
None	_progress (str message)

Detailed Description

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)

Function Documentation

_emit_list()

None oct.mutation.command._emit_list ( Path target, Path | None root, bool json_mode )

protected

Write the enumeration for ``--list`` in the requested output mode.

Definition at line 141 of file command.py.

Here is the caller graph for this function:

_id_anchor()

Path | None oct.mutation.command._id_anchor ( Path target )

protected

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.

Definition at line 125 of file command.py.

Here is the caller graph for this function:

_progress()

None oct.mutation.command._progress ( str message )

protected

Write one progress line to stderr, keeping stdout free for the report.

Definition at line 159 of file command.py.

mutate()

None oct.mutation.command.mutate	(	Path	target,
		Path | None	tests,
		int	timeout,
		bool	json_mode,
		bool	list_mode )

Mutate a file and report which mutants the tests fail to notice.

Definition at line 93 of file command.py.

Here is the call graph for this function: