Classes
class	ParseFailure
class	FunctionResult
class	AnalysisReport

Functions
AnalysisReport	analyze_paths (Sequence[str\|Path] paths, str\|Path\|None coverage_data=None)
list[Path]	discover_python_files (Sequence[str\|Path] paths)
bool	is_excluded_path (Path path, Path scan_root)
FunctionResult	_without_coverage (FunctionComplexity record)
FunctionResult	_with_coverage (CoveredFunction item)
tuple[object,...]	_complexity_sort_key (FunctionResult item)
tuple[object,...]	_crap_sort_key (FunctionResult item)
str	_coverage_absence_message ()
str	render_human (AnalysisReport report, int\|None top=None)
str	_span (FunctionResult item)
str	_normalized_path (Path path)
str	relative_display_path (str\|Path file, str\|Path root)
str	function_identity (str\|Path file, str qualname, str\|Path root)

Variables
	_EXCLUDED_DIRECTORY_NAMES

Detailed Description

Purpose
-------
Provide shared analysis, ordering, and rendering for command adapters.

Responsibilities
----------------
- Discover Python files while excluding environment and build trees.
- Record every parse failure instead of silently omitting files.
- Produce stable worst-first CC or CRAP ordering.
- Render full JSON data and compact ASCII human output.
- Expose the shared relative-path display that gate output and baseline
  identities are built from.

Diagnostics
-----------
Domain: OCT-COMPLEXITY
Levels:
    L2 - analysis lifecycle
    L3 - file and result details
    L4 - deep tracing

Contracts
---------
- JSON results are never truncated by ``--top``.
- CC-only rows explicitly identify coverage as not measured.
- The service measures and never gates.

Dependencies
------------
- oct.complexity.coverage (optional coverage mapping)
- oct.complexity.engine (complexity records)
- oct.complexity.metrics (CRAP formula)

Function Documentation

◆ _complexity_sort_key()

tuple[object, ...] oct.complexity.service._complexity_sort_key ( FunctionResult item )

protected

Sort CC-only rows worst-first with deterministic tie breaking.

Definition at line 236 of file service.py.

◆ _coverage_absence_message()

str oct.complexity.service._coverage_absence_message ( )

protected

Explain exactly why CRAP columns are absent in CC-only mode.

Definition at line 257 of file service.py.

Here is the caller graph for this function:

◆ _crap_sort_key()

tuple[object, ...] oct.complexity.service._crap_sort_key ( FunctionResult item )

protected

Sort covered rows by CRAP worst-first, then complexity.

Definition at line 246 of file service.py.

◆ _normalized_path()

str oct.complexity.service._normalized_path ( Path path )

protected

Return a deterministic filesystem identity key.

Definition at line 304 of file service.py.

Here is the caller graph for this function:

◆ _span()

str oct.complexity.service._span ( FunctionResult item )

protected

Return one source span suitable for terminal output.

Definition at line 299 of file service.py.

◆ _with_coverage()

FunctionResult oct.complexity.service._with_coverage ( CoveredFunction item )

protected

Convert a covered record and calculate its CRAP score.

Definition at line 220 of file service.py.

Here is the caller graph for this function:

◆ _without_coverage()

FunctionResult oct.complexity.service._without_coverage ( FunctionComplexity record )

protected

Convert an engine record into an explicit CC-only result.

Definition at line 204 of file service.py.

Here is the caller graph for this function:

◆ analyze_paths()

AnalysisReport oct.complexity.service.analyze_paths	(	Sequence[str \| Path]	paths,
		str \| Path \| None	coverage_data = None )

Analyze Python paths and optionally enrich every record with coverage.

Definition at line 128 of file service.py.

Here is the call graph for this function:

◆ discover_python_files()

list[Path] oct.complexity.service.discover_python_files ( Sequence[str | Path] paths )

Return unique Python files under paths with build/cache trees excluded.

Definition at line 175 of file service.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ function_identity()

str oct.complexity.service.function_identity	(	str \| Path	file,
		str	qualname,
		str \| Path	root )

Return the stable ``relpath::qualname`` identity of one function.

A renamed or moved function is honestly a new function under this
identity, which is the point: the ratchet grandfathers recorded debt,
not the name it happened to carry.

Definition at line 325 of file service.py.

◆ is_excluded_path()

bool oct.complexity.service.is_excluded_path	(	Path	path,
		Path	scan_root )

Return whether a discovered path crosses an excluded directory.

Definition at line 195 of file service.py.

Here is the caller graph for this function:

◆ relative_display_path()

str oct.complexity.service.relative_display_path	(	str \| Path	file,
		str \| Path	root )

Return *file* relative to *root* with forward separators.

Gate output and baseline identities have to survive being read on another
machine, so the separator is normalised and the path is made relative
whenever it lies under *root*. A file outside *root* (a different drive,
a temporary fixture) keeps its absolute POSIX spelling rather than
growing a misleading chain of parent segments.

Definition at line 309 of file service.py.

◆ render_human()

str oct.complexity.service.render_human	(	AnalysisReport	report,
		int \| None	top = None )

Render a compact worst-first ASCII report for terminal users.

Definition at line 270 of file service.py.

Variable Documentation

◆ _EXCLUDED_DIRECTORY_NAMES

oct.complexity.service._EXCLUDED_DIRECTORY_NAMES

protected

Initial value:

=  frozenset(
    {
        ".git",
        ".hg",
        ".mypy_cache",
        ".nox",
        ".pytest_cache",
        ".ruff_cache",
        ".svn",
        ".tox",
        ".venv",
        "__pycache__",
        "build",
        "dist",
        "node_modules",
        "tests",
        "venv",
    }
)

Definition at line 56 of file service.py.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ _complexity_sort_key()

◆ _coverage_absence_message()

◆ _crap_sort_key()

◆ _normalized_path()

◆ _span()

◆ _with_coverage()

◆ _without_coverage()

◆ analyze_paths()

◆ discover_python_files()

◆ function_identity()

◆ is_excluded_path()

◆ relative_display_path()

◆ render_human()

Variable Documentation

◆ _EXCLUDED_DIRECTORY_NAMES