feat: codegraphcontext analyze complexity threshold flag has no documented output format and no machine-readable export — CI integration is impossible without parseable output #1333

🚀 Problem Statement

The README documents:

# Find complex code
codegraphcontext analyze complexity --threshold 10

This command returns functions whose cyclomatic complexity exceeds the
given threshold. However, the current output is human-readable text
only — there is no JSON, CSV, or machine-readable output mode.

Why This Is a CI/CD Blocker

The --threshold flag exists precisely for enforcement use cases:
"In this codebase, no function may have cyclomatic complexity above 10."
This is a standard quality gate in CI pipelines (similar to flake8's
--max-complexity flag).

But enforcing this in CI requires:

1. A non-zero exit code when violations are found
2. Machine-readable output that CI reporters can parse

Currently:

• codegraphcontext analyze complexity --threshold 10 exits with code 0
  regardless of how many violations are found.
• Output is formatted text, not parseable JSON.
• There is no way to integrate this with GitHub Actions, pytest, or any
  standard CI tool.

Concrete CI Use Case That Currently Fails

# .github/workflows/quality.yml — this DOES NOT work today
- name: Check code complexity
  run: |
    codegraphcontext analyze complexity --threshold 10
    # Always exits 0 — violations are never caught in CI

Compared to what users expect (the flake8 pattern):

- name: Check code complexity
  run: flake8 --max-complexity=10 src/
  # Exits non-zero when violations found → PR blocked

✅ Proposed Solution

1. Non-zero exit code on threshold violations

# In src/codegraphcontext/analyzers/complexity.py

def analyze_complexity(threshold: int, output_format: str = "text") -> int:
    """
    Returns number of violations found.
    Caller should sys.exit(1) if violations > 0.
    """
    violations = _find_violations(threshold)
    _output(violations, output_format)
    return len(violations)

# In CLI handler:
violations = analyze_complexity(threshold=args.threshold, output_format=args.format)
if violations > 0:
    sys.exit(1)  # ← This is the critical missing line

2. --format flag for machine-readable output

# Human-readable (default, current behavior)
codegraphcontext analyze complexity --threshold 10

# JSON output for CI parsing
codegraphcontext analyze complexity --threshold 10 --format json

# CSV for spreadsheet/dashboard integration
codegraphcontext analyze complexity --threshold 10 --format csv

JSON output schema

{
  "threshold": 10,
  "violations_count": 3,
  "violations": [
    {
      "function": "process_order",
      "file": "src/orders.py",
      "line": 45,
      "complexity": 23,
      "exceeds_by": 13
    },
    {
      "function": "validate_input",
      "file": "src/api/validators.py",
      "line": 112,
      "complexity": 17,
      "exceeds_by": 7
    }
  ]
}

3. GitHub Actions example in documentation

# docs/CI_INTEGRATION.md — new file
- name: Enforce complexity threshold
  run: |
    codegraphcontext index .
    codegraphcontext analyze complexity --threshold 10 --format json \
      | tee complexity-report.json
  # Exits non-zero if any function exceeds threshold → PR blocked

- name: Upload complexity report
  uses: actions/upload-artifact@v4
  with:
    name: complexity-report
    path: complexity-report.json

Files to Modify

📊 Impact

The --threshold flag on analyze complexity currently has no
enforcement power — it describes violations but cannot block anything.
Adding exit codes and machine-readable output converts a reporting
tool into an enforcement tool, which is the primary use case for a
complexity threshold flag. This is directly analogous to the --exit-zero
pattern in flake8 and the --max-warnings pattern in ESLint, both of
which are standard CI tooling patterns.

Suggested labels: enhancement, CI/CD, intermediate

I would like to work on this. Could you assign it to me?