Skip to content
Arxo Arxo

Cycle Microscope

Cycle Microscope

Section titled “Cycle Microscope”

The Cycle Microscope is the detailed per-cycle view that Arxo builds for each cycle it finds. It shows exactly which files are in the cycle, how they connect, what depends on the cycle from outside, and — when git history is enabled — which file to refactor first.

For an overview, see Circular Dependencies. For how to enable git-based priority, see Git History Integration.

What You Get Per Cycle

Section titled “What You Get Per Cycle”

For every cycle (SCC with more than one node), the UI and JSON include:

1. Nodes and Edges

Section titled “1. Nodes and Edges”
  • nodes — List of module IDs (files or grouped nodes) in this cycle
  • edges — Dependency pairs inside the cycle (A→B, B→C, etc.)

This is the raw structure of the cycle: who depends on whom inside the loop.

2. Boundary Edges

Section titled “2. Boundary Edges”
  • boundary_in — Edges from outside the cycle into the cycle (who imports into this cycle)
  • boundary_out — Edges from inside the cycle to the outside (what the cycle depends on externally)

Boundary edges help you see:

  • boundary_out: Good candidates to extract or invert — the cycle’s dependencies on the rest of the codebase
  • boundary_in: Who is affected when you change or break the cycle

3. Node Table (Refactor Priority)

Section titled “3. Node Table (Refactor Priority)”

When git history is enabled, each node in the cycle gets:

ColumnMeaningHow to use it
node_idFile or module pathIdentifies the node
centralityBetweenness within the cycle (0–1)Higher = more “hub-like” in the cycle
churnNumber of commits touching this fileHigher = file changes often
hotspot_scorechurn × centralityRefactor priority — fix higher scores first

Sort the table by hotspot_score descending to see which file in the cycle will give the biggest payoff when refactored.

Example (JSON)

Section titled “Example (JSON)”
{
  "scc_details": [
    {
      "scc_idx": 0,
      "nodes": ["src/cli/prettier.js", "src/standalone.js"],
      "edges": [
        ["src/cli/prettier.js", "src/standalone.js"],
        ["src/standalone.js", "src/cli/prettier.js"]
      ],
      "boundary_in": [["src/index.js", "src/cli/prettier.js"]],
      "boundary_out": [["src/cli/prettier.js", "src/utils/index.js"]],
      "node_table": [
        {
          "node_id": "src/cli/prettier.js",
          "centrality": 0.24,
          "churn": 87,
          "hotspot_score": 20.88
        },
        {
          "node_id": "src/standalone.js",
          "centrality": 0.15,
          "churn": 23,
          "hotspot_score": 3.45
        }
      ]
    }
  ]
}

Here, src/cli/prettier.js has the highest hotspot score — prioritize refactoring that file or its edges to break the cycle.

Charts

Section titled “Charts”

When cycles exist, Arxo can add a bar chart of cycle sizes (e.g. “Cycle 1”, “Cycle 2”, … with node counts). That helps you see at a glance how many cycles you have and how large the biggest ones are.

How to Use the Microscope

Section titled “How to Use the Microscope”
  1. Find the largest or most painful cycle — Use scc.max_cycle_size and the cycle list.
  2. Open that cycle’s details — Use scc_details for that cycle (e.g. by scc_idx or by matching nodes).
  3. Sort by hotspot_score — Fix the top-ranked files first (requires git history).
  4. Look at boundary_out — Prefer breaking edges that go from the cycle to shared or stable modules.
  5. Use cycle-cut candidates — For function-level cycles, use the suggested edges (see Function-Level Cycles).

Next Steps

Section titled “Next Steps”