check_cycles

check_cycles

Quickly check for circular dependencies (import cycles) in your codebase. This tool uses Strongly Connected Components (SCC) analysis to detect cycles without running a full architecture analysis.

Note

This is the fastest tool for pre-commit or pre-PR checks. Use it when you only care about cycles, not other metrics.

Parameters

Parameter	Type	Required	Description
project_path	string	Yes	Absolute or relative path to the project root directory

Response

Returns a JSON summary with cycle statistics.

Response Schema

{
  "scc": {
    "component_count": "number",           // Number of SCC components (higher is healthier)
    "cycle_count": "number",               // Number of actual cycles
    "max_cycle_size": "number",            // Size of the largest cycle (0 = no cycles)
    "total_nodes_in_cycles": "number"     // Total modules trapped in cycles
  },
  "violations_count": "number"             // Policy violations triggered by cycles
}

Interpreting Results

max_cycle_size	Interpretation
0	✅ No circular dependencies detected
2	⚠️ Simple two-module cycle (e.g., A imports B, B imports A)
3-10	⚠️ Moderate cycle complexity
>10	🚨 Complex circular dependency — difficult to refactor

• cycle_count — Number of distinct cycle groups. A value of 0 means no cycles.
• component_count — Number of SCC components. In acyclic graphs this is close to total module count.
• total_nodes_in_cycles — Sum of all modules participating in any cycle. Useful for estimating refactoring scope.

Examples

No cycles detected

Request:

{
  "project_path": "."
}

Response:

{
  "scc": {
    "component_count": 183,
    "cycle_count": 0,
    "max_cycle_size": 0,
    "total_nodes_in_cycles": 0
  },
  "violations_count": 0
}

Cycles detected

Request:

{
  "project_path": "/path/to/project"
}

Response:

{
  "scc": {
    "component_count": 175,
    "cycle_count": 2,
    "max_cycle_size": 5,
    "total_nodes_in_cycles": 8
  },
  "violations_count": 1
}

Interpretation:

• 2 distinct cycle groups exist
• The largest cycle involves 5 modules
• 8 modules total are trapped in cycles
• 1 policy violation triggered (likely scc.max_cycle_size > 0)

Workflow

Use this tool as the first step in a multi-step architecture check:

1. check_cycles → if max_cycle_size > 0, proceed to step 2
2. get_hotspots → identify which modules are in cycles
3. suggest_refactors → get recommendations for breaking cycles

See Workflows: Quick health check for a full example.

Error Cases

Error	Cause	Solution
missing required parameter: project_path	project_path not provided	Include project_path in request
No such file or directory	Invalid project path	Verify path exists and is accessible
scc metric not in results	Engine failed to compute SCC	Check project structure and language support

Performance

• Speed: 1-5 seconds for most projects (uses the quick preset internally)
• Caching: Does not use cache (intentionally — always fresh for pre-commit checks)
• Scalability: Handles projects with 10k+ files efficiently

Tip

For very large monorepos (50k+ files), consider using analyze_architecture with the quick preset and caching enabled for repeated checks.

Related Tools

• analyze_architecture — Full analysis including SCC and other metrics
• get_hotspots — Find which modules are in cycles
• suggest_refactors — Get cycle-breaking recommendations

Related Guides

• Breaking Cycles — Step-by-step guide to fixing circular dependencies
• SCC Interpretation — Understanding SCC results
• SCC Policy — Configuring cycle detection policies

CLI Equivalent

# Fast cycle check (same as check_cycles)
arxo analyze --preset quick --format json | jq '.results[] | select(.id=="scc")'

# Or use the dedicated cycles command (if available)
arxo cycles