CLI and Integration

CLI and Integration

CLI usage, integrations, advanced features, and troubleshooting. For an overview, see Circular Dependencies.

Advanced Features

Function-Level Cycles

When call-graph data is available, SCC also emits function-level keys:

{
  "scc.function.cycle_count": 507,
  "scc.function.call_mass": 172,
  "scc.function.cycle_cut_candidates_count": 4
}

Use case: find circular call paths even when module-level imports are mostly clean.

SCC Config Reference

Configure SCC under metrics[].config for the metric with id: scc.

Key	Type	Default	What it controls
use_git_history	bool	false	Load git history and populate churn / hotspot_score in cycle details
emit_findings	bool	true	Emit cycle findings in results[].findings
max_cycles_in_ui	number	50	Cap number of cycles included in ui_schemas.scc.scc_details
edge_mode	string	all	Edge set used for SCC: all, runtime_only, structural_only
max_findings	number	unset	Maximum number of SCC findings emitted
emit_function_findings	bool	true	Emit findings for function-level cycles when call graph exists

Example:

metrics:
  - id: scc
    config:
      edge_mode: all
      emit_findings: true
      emit_function_findings: true
      max_cycles_in_ui: 50
      max_findings: 100
      use_git_history: true

Compatibility note: SCC also accepts these keys under a nested scc: object inside the metric config, but direct keys (shown above) are recommended.

If edge_mode is invalid, analysis returns an error for SCC config parsing.

CLI Usage

Basic Analysis

# Detect cycles
arxo analyze

# JSON output
arxo analyze --format json

# Run only SCC
arxo analyze --metric scc

With Policy

# Enforce SCC policy from config
arxo analyze --config arxo.yml

# Exit code 1 if policy fails
echo $?

Detailed Output

# Module-level SCC numeric keys
arxo analyze --format json | jq '.results[] | select(.id=="scc") | .data[] | select(.key|test("^scc\\.(component_count|cycle_count|max_cycle_size|total_nodes_in_cycles)$"))'

# Function-level numeric keys
arxo analyze --format json | jq '.results[] | select(.id=="scc") | .data[] | select(.key|startswith("scc.function."))'

# Per-cycle details (cycle microscope payload)
arxo analyze --format json | jq '.ui_schemas.scc.scc_details[] | select((.nodes | length) > 1)'

# Function call-cycle cut candidates (UI category)
arxo analyze --format json | jq '.ui_schemas.scc.issues.categories.cycle_cut_candidates.critical'

# Structured SCC outputs in result data
arxo analyze --format json | jq '.results[] | select(.id=="scc") | .data[] | select(.key|test("^scc\\.(cycle_summary|cut_candidates|cycles|top_cycles_by_risk|top_cut_candidates|condensed_dag|config)$"))'

Integration

Pre-commit Hook

.pre-commit-config.yaml

repos:
  - repo: local
    hooks:
      - id: arxo-scc
        name: Check for circular dependencies
        entry: arxo analyze --metric scc --format json
        language: system
        pass_filenames: false

GitHub Actions

.github/workflows/architecture.yml

name: Architecture Checks
on: [push, pull_request]

jobs:
  cycles:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: arxo-dev/setup-arxo@v1
      - run: arxo analyze --metric scc --config arxo.yml

IDE

The Arxo IDE can surface cycles inline:

• diagnostics on imports contributing to cycles
• cycle path drill-down
• quick metric access for cycle counts and sizes

Troubleshooting

”No cycles detected” but code has circular imports

Cause: Grouping level is too coarse.

Solution:

data:
  import_graph:
    group_by: file

Large cycle reported but hard to locate

Cause: The cycle spans many intermediate modules.

Solution:

arxo analyze --format json | jq '.ui_schemas.scc.scc_details[] | select((.nodes | length) > 10)'

Churn and hotspot_score are zero

Cause: git history was not loaded for SCC.

Solution:

metrics:
  - id: scc
    config:
      use_git_history: true

Debug:

ARXO_SCC_DEBUG=1 arxo analyze

Expected debug line:

[scc] use_git_history=true git_history=Some edge_mode=all

Understanding scc.module.* vs scc.*

Canonical SCC metric keys emitted by the plugin are scc.* and scc.function.*.

Some downstream consumers (for compatibility) may expose mirrored names like scc.module.max_cycle_size. Treat them as aliases when present.

For policies and new integrations, prefer canonical scc.* keys.

Further Reading

• Circular Dependencies: overview
• SCC Keys and Output Contract: full config/key contract
• Git History Integration: churn and hotspot ranking
• Function-Level Cycles: call-graph cycles and cut candidates
• Performance: benchmarks and comparison
• Fixing Cycles: refactoring process
• CI Integration: automation patterns