__main__.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/complexity/__main__.py
 
"""
Purpose
-------
Expose the complexity instrument through ``python -m oct.complexity``.
 
Responsibilities
----------------
- Parse module-command paths and output options.
- Run the shared measurement service for MAIN-tree probes.
- Return stable process exit codes for invalid options and missing inputs.
 
Diagnostics
-----------
Domain: OCT-COMPLEXITY
Levels:
    L2 - command lifecycle
    L3 - option and output details
    L4 - deep tracing
 
Contracts
---------
- Console output is ASCII and JSON mode writes no extra stdout text.
- The adapter measures and never gates.
- Human ``--top`` never truncates JSON data.
 
Dependencies
------------
- oct.complexity.service (analysis and rendering)
- oct.complexity.coverage (missing coverage.py error, reported as exit 2)
"""
 
# OCT-LINT: disable-file=dbg_usage reason="Diagnostics would contaminate the module command's JSON-only stdout contract"
# OCT-LINT: disable-file=dbg_import reason="Diagnostics would contaminate the module command's JSON-only stdout contract"
 
from __future__ import annotations
 
import argparse
import json
import sys
from pathlib import Path
from typing import Sequence
 
from oct.complexity.coverage import CoverageUnavailableError
from oct.complexity.service import analyze_paths, render_human
 
 
def _parser() -> argparse.ArgumentParser:
    """Build the module command's argument parser."""
    parser = argparse.ArgumentParser(
        prog="python -m oct.complexity",
        description="Measure per-function complexity and optional CRAP scores.",
    )
    parser.add_argument(
        "paths",
        nargs="*",
        type=Path,
        help="Python files or directories (default: current directory).",
    )
    parser.add_argument(
        "--coverage-data",
        type=Path,
        default=None,
        help="Existing coverage.py data file to map offline.",
    )
    parser.add_argument(
        "--json",
        action="store_true",
        dest="json_mode",
        help="Emit the full machine-readable report.",
    )
    parser.add_argument(
        "--top",
        type=int,
        default=None,
        help="Limit human output to the worst N functions.",
    )
    return parser
 
 
def main(argv: Sequence[str] | None = None) -> int:
    """Run the module command and return its process exit code."""
    args = _parser().parse_args(argv)
    if args.top is not None and args.top < 1:
        print("error: --top must be at least 1", file=sys.stderr)
        return 2
    targets = args.paths or [Path.cwd()]
    try:
        report = analyze_paths(targets, coverage_data=args.coverage_data)
    except (CoverageUnavailableError, FileNotFoundError) as exc:
        print(f"error: {exc}", file=sys.stderr)
        return 2
    if args.json_mode:
        print(json.dumps(report.to_dict(), indent=2, sort_keys=True))
    else:
        print(render_human(report, top=args.top))
    return 0
 
 
if __name__ == "__main__":
    raise SystemExit(main())