Classes
class	GateRefusalError
class	Thresholds
class	Breach
class	Verdict

Functions
Thresholds	resolve_thresholds (int\|None flag_max_cc, float\|None flag_max_crap, dict\|None config)
str\|None	_source (object flag_value, object config_value)
int\|float\|None	_coerce_limit (object value, str key, bool as_int)
tuple[Breach,...]	evaluate (Sequence[FunctionResult] results, Thresholds thresholds, str\|Path root, Mapping[str, "BaselineEntry"]\|None baseline=None)
tuple[str,...]	_worsened_metrics (FunctionResult item, tuple[str,...] metrics, "BaselineEntry" recorded)
str	_reason (Mapping[str, "BaselineEntry"]\|None baseline, "BaselineEntry \| None" recorded, tuple[str,...] metrics)
tuple[str,...]	_breached_metrics (FunctionResult item, Thresholds thresholds)
Verdict	build_verdict (Thresholds thresholds, Sequence[Breach] breaches, str\|None baseline=None, int\|None baseline_functions=None, str\|None baseline_written=None, int\|None baseline_written_functions=None)
str	render_verdict (Verdict verdict)
list[str]	_render_outcome (Verdict verdict)
str	_number (float value)

Variables
int	ADVISORY_MAX_CC = 15
int	ADVISORY_MAX_CRAP = 30
int	EXIT_CLEAN = 0
int	EXIT_BREACH = 2
int	EXIT_REFUSAL = 3
str	SOURCE_FLAG = "flag"
str	SOURCE_CONFIG = "octrc"
str	CONFIG_SECTION = "complexity"

Detailed Description

Purpose
-------
Turn measurements into a gate-callable verdict with a real exit code.

Responsibilities
----------------
- Resolve thresholds from explicit flags over an ``.octrc.json`` section.
- Apply the don't-get-worse ratchet against a recorded baseline.
- Name every breaching function as ``relpath:line qualname CC=n [CRAP=m]``.
- Carry the verdict as both machine fields and compact ASCII lines.

Diagnostics
-----------
Domain: OCT-COMPLEXITY
Levels:
    L2 - verdict lifecycle
    L3 - threshold and breach details
    L4 - deep tracing

Contracts
---------
- No active threshold means no verdict, so today's output is unchanged.
- Exit 0 is clean, exit 2 is at least one breach, exit 3 is a named refusal.
- A malformed threshold is refused by name and never silently ignored.
- The module imports only the Python standard library and sibling measurement
  modules, so it stays callable from a zero-dependency context.

Dependencies
------------
- oct.complexity.service (result rows and relative-path display)
- oct.complexity.baseline (lazy; BaselineEntry type hints for the ratchet comparison)

Function Documentation

◆ _breached_metrics()

tuple[str, ...] oct.complexity.thresholds._breached_metrics	(	FunctionResult	item,
		Thresholds	thresholds )

protected

Return which active metrics this one function exceeds.

Definition at line 330 of file thresholds.py.

Here is the caller graph for this function:

◆ _coerce_limit()

int \| float \| None oct.complexity.thresholds._coerce_limit	(	object	value,
		str	key,
		bool	as_int )

protected

Validate one configured limit or refuse it by name.

Definition at line 208 of file thresholds.py.

Here is the caller graph for this function:

◆ _number()

str oct.complexity.thresholds._number ( float value )

protected

Render a limit without a trailing ``.0`` on whole numbers.

Definition at line 401 of file thresholds.py.

◆ _reason()

str oct.complexity.thresholds._reason	(	Mapping[str, "BaselineEntry"] \| None	baseline,
		"BaselineEntry \| None"	recorded,
		tuple[str, ...]	metrics )

protected

Return the human-readable cause of one breach.

Definition at line 308 of file thresholds.py.

Here is the caller graph for this function:

◆ _render_outcome()

list[str] oct.complexity.thresholds._render_outcome ( Verdict verdict )

protected

Return the verdict's outcome lines, breaches included.

Definition at line 386 of file thresholds.py.

Here is the caller graph for this function:

◆ _source()

str \| None oct.complexity.thresholds._source	(	object	flag_value,
		object	config_value )

protected

Return which input supplied the effective limit, if any did.

Definition at line 199 of file thresholds.py.

Here is the caller graph for this function:

◆ _worsened_metrics()

tuple[str, ...] oct.complexity.thresholds._worsened_metrics	(	FunctionResult	item,
		tuple[str, ...]	metrics,
		"BaselineEntry"	recorded )

protected

Keep only the over-threshold metrics that are worse than recorded.

A recorded ``crap`` of ``None`` means the baseline was written without
coverage data, so there is no accepted value to sit at or below. That
fails closed: an unrecorded metric is never grandfathered.

Definition at line 285 of file thresholds.py.

Here is the caller graph for this function:

◆ build_verdict()

Verdict oct.complexity.thresholds.build_verdict	(	Thresholds	thresholds,
		Sequence[Breach]	breaches,
		str \| None	baseline = None,
		int \| None	baseline_functions = None,
		str \| None	baseline_written = None,
		int \| None	baseline_written_functions = None )

Return the verdict for one gate-mode invocation.

Definition at line 347 of file thresholds.py.

◆ evaluate()

tuple[Breach, ...] oct.complexity.thresholds.evaluate	(	Sequence[FunctionResult]	results,
		Thresholds	thresholds,
		str \| Path	root,
		Mapping[str, "BaselineEntry"] \| None	baseline = None )

Return every function that fails the active thresholds, worst first.

Without a baseline, failing means exceeding a threshold. With one, the
ratchet applies: a function the baseline never saw fails on the threshold
alone, and a recorded function fails only when it is BOTH over the
threshold and strictly worse than its recorded value. Existing debt held
at or below its recorded value never fails - this is hygiene, not
rigidity.

``results`` arrives already ordered worst-first by the service, so the
breach list names the most severe function first.

Definition at line 235 of file thresholds.py.

Here is the call graph for this function:

◆ render_verdict()

str oct.complexity.thresholds.render_verdict ( Verdict verdict )

Render the verdict as compact ASCII lines for terminal users.

Definition at line 369 of file thresholds.py.

Here is the call graph for this function:

◆ resolve_thresholds()

Thresholds oct.complexity.thresholds.resolve_thresholds	(	int \| None	flag_max_cc,
		float \| None	flag_max_crap,
		dict \| None	config )

Resolve the effective thresholds, with flags overriding the config.

``config`` is the whole ``.octrc.json`` document; only its optional
``complexity`` object is read. A malformed value raises
:class:`GateRefusalError` rather than degrading to "no threshold",
because a silently inactive gate reads exactly like a passing one.

Definition at line 168 of file thresholds.py.

Here is the call graph for this function:

Variable Documentation

◆ ADVISORY_MAX_CC

int oct.complexity.thresholds.ADVISORY_MAX_CC = 15

Definition at line 60 of file thresholds.py.

◆ ADVISORY_MAX_CRAP

int oct.complexity.thresholds.ADVISORY_MAX_CRAP = 30

Definition at line 61 of file thresholds.py.

◆ CONFIG_SECTION

str oct.complexity.thresholds.CONFIG_SECTION = "complexity"

Definition at line 70 of file thresholds.py.

◆ EXIT_BREACH

int oct.complexity.thresholds.EXIT_BREACH = 2

Definition at line 64 of file thresholds.py.

◆ EXIT_CLEAN

int oct.complexity.thresholds.EXIT_CLEAN = 0

Definition at line 63 of file thresholds.py.

◆ EXIT_REFUSAL

int oct.complexity.thresholds.EXIT_REFUSAL = 3

Definition at line 65 of file thresholds.py.

◆ SOURCE_CONFIG

str oct.complexity.thresholds.SOURCE_CONFIG = "octrc"

Definition at line 68 of file thresholds.py.

◆ SOURCE_FLAG

str oct.complexity.thresholds.SOURCE_FLAG = "flag"

Definition at line 67 of file thresholds.py.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ _breached_metrics()

◆ _coerce_limit()

◆ _number()

◆ _reason()

◆ _render_outcome()

◆ _source()

◆ _worsened_metrics()

◆ build_verdict()

◆ evaluate()

◆ render_verdict()

◆ resolve_thresholds()

Variable Documentation

◆ ADVISORY_MAX_CC

◆ ADVISORY_MAX_CRAP

◆ CONFIG_SECTION

◆ EXIT_BREACH

◆ EXIT_CLEAN

◆ EXIT_REFUSAL

◆ SOURCE_CONFIG

◆ SOURCE_FLAG