oct.complexity.command Namespace Reference

Classes
class	GateRefusal

Functions
None	complexity (click.Context ctx, tuple[Path,...] paths, Path|None coverage_data, bool json_mode, int|None top, int|None max_cc, float|None max_crap, bool changed, Path|None baseline_path, Path|None write_baseline_path)
None	_check_baseline_options (Thresholds thresholds, Path|None baseline_path, Path|None write_baseline_path)
Verdict	_build_gate_verdict (AnalysisReport report, Thresholds thresholds, Path root, Path|None baseline_path, Path|None write_baseline_path)
tuple[Path, click.ClickException|None]	_resolve_root (click.Context ctx)
Thresholds	_resolve_gate_thresholds (Path root, int|None max_cc, float|None max_crap, Path|None coverage_data)
tuple[Path,...]	_changed_targets (Path root, tuple[Path,...] paths, bool json_mode)
tuple[Path,...]	_resolve_targets (tuple[Path,...] paths, Path root, click.ClickException|None root_error)
None	_emit_report (AnalysisReport report, bool json_mode, int|None top, Verdict|None verdict=None)

Detailed Description

Purpose
-------
Expose the on-demand complexity instrument through Click.

Responsibilities
----------------
- Parse paths, coverage data, JSON mode, and human truncation options.
- Parse the plan-226 gate options: thresholds and their exit-code contract.
- Scope a call to the git-modified file set under ``--changed``.
- Record and compare the don't-get-worse baseline.
- Default analysis to the discovered Option C project root.
- Convert dependency and path failures into clear CLI errors.

Diagnostics
-----------
Domain: OCT-COMPLEXITY
Levels:
    L2 - command lifecycle
    L3 - option and output details
    L4 - deep tracing

Contracts
---------
- ``--top`` affects human output only.
- With no threshold active the command is informational and exits 0, byte for
  byte as it did before plan 226.
- With a threshold active the command exits 0 when clean, 2 when any function
  breaches, and 3 when the call cannot be honestly evaluated.
- Machine-readable stdout contains JSON only.

Dependencies
------------
- click (CLI adapter)
- oct.complexity.baseline (ratchet document I/O)
- oct.complexity.service (analysis and rendering)
- oct.complexity.thresholds (verdict and exit-code contract)
- oct.core.octrc (optional complexity configuration section)
- oct.core.project_root (default target discovery)
- oct.complexity.coverage (missing coverage.py error, raised as a CLI error)
- oct.core.git (lazy; git-modified Python files for --changed)

Function Documentation

_build_gate_verdict()

Verdict oct.complexity.command._build_gate_verdict ( AnalysisReport report, Thresholds thresholds, Path root, Path | None baseline_path, Path | None write_baseline_path )

protected

Load or write a baseline as asked, then judge the measurements.

Definition at line 212 of file command.py.

Here is the caller graph for this function:

_changed_targets()

tuple[Path, ...] oct.complexity.command._changed_targets ( Path root, tuple[Path, ...] paths, bool json_mode )

protected

Return the git-modified Python files, scoped exactly as the linter is.

Discovery is :func:`oct.core.git.git_changed_files`, the same helper
``oct lint --changed`` uses, and the result passes through the service's
own exclusion set so ``--changed`` narrows the measured universe without
widening it. A git failure is refused rather than collapsed to an empty
list: an empty measurement reads as a pass, and a gate that passes
because git broke is worse than one that stops.

Definition at line 278 of file command.py.

Here is the caller graph for this function:

_check_baseline_options()

None oct.complexity.command._check_baseline_options ( Thresholds thresholds, Path | None baseline_path, Path | None write_baseline_path )

protected

Refuse baseline combinations that could not produce an honest verdict.

Definition at line 192 of file command.py.

Here is the caller graph for this function:

_emit_report()

None oct.complexity.command._emit_report ( AnalysisReport report, bool json_mode, int | None top, Verdict | None verdict = None )

protected

Write the report, adding the verdict only when a gate mode is active.

Definition at line 322 of file command.py.

Here is the caller graph for this function:

_resolve_gate_thresholds()

Thresholds oct.complexity.command._resolve_gate_thresholds ( Path root, int | None max_cc, float | None max_crap, Path | None coverage_data )

protected

Resolve thresholds and refuse a CRAP limit that cannot be measured.

Definition at line 258 of file command.py.

Here is the caller graph for this function:

_resolve_root()

tuple[Path, click.ClickException | None] oct.complexity.command._resolve_root ( click.Context ctx )

protected

Return the project root, tolerating undiscoverable roots.

Configuration lookup and relative-path display need a root even when the
caller measures an explicit path outside any project, so a failed
discovery falls back to the working directory and the original error is
handed back for the one caller that must still fail on it. An explicit
``--root-dir`` is never softened: that error is the operator's own.

Definition at line 241 of file command.py.

Here is the caller graph for this function:

_resolve_targets()

tuple[Path, ...] oct.complexity.command._resolve_targets ( tuple[Path, ...] paths, Path root, click.ClickException | None root_error )

protected

Return the paths to measure, defaulting to the project root.

Definition at line 309 of file command.py.

Here is the caller graph for this function:

complexity()

None oct.complexity.command.complexity	(	click.Context	ctx,
		tuple[Path, ...]	paths,
		Path | None	coverage_data,
		bool	json_mode,
		int | None	top,
		int | None	max_cc,
		float | None	max_crap,
		bool	changed,
		Path | None	baseline_path,
		Path | None	write_baseline_path )

Measure per-function cyclomatic complexity and optional CRAP scores.

Definition at line 153 of file command.py.

Here is the call graph for this function: