detect command

detect — Find Circular Dependencies

Detects circular dependencies in your dependency graph using DFS-based cycle detection.

codebase-vis detect

How It Works

1. Loads graph.json from codebase-out/
2. Runs DFS (depth-first search) on file-only nodes (skips entities and external packages)
3. When a back-edge is found (a node reachable from itself in the current DFS path), it records a cycle
4. Deduplicates cycles using canonical key rotation
5. Caps output at 200 cycles (real codebases can have combinatorial explosions)
6. Writes cycle details to cycles.json

Canonical Key Deduplication

The same cycle can be detected starting from different nodes. For example, A→B→C→A and B→C→A→B are the same cycle. The algorithm handles this by:

1. Rotating the cycle path so the alphabetically-minimum node is first
2. Joining with | to form a canonical key
3. Only recording cycles with unique canonical keys

Output

Terminal

Prints each detected cycle as a chain:

Cycle 1 (3 files):
  src/utils/a.js
  → src/utils/b.js
  → src/utils/c.js
  → src/utils/a.js

cycles.json

Written to codebase-out/cycles.json with detailed data:

[
  {
    "id": "cycle-0",
    "size": 3,
    "files": ["src/utils/a.js", "src/utils/b.js", "src/utils/c.js"],
    "edges": [
      { "source": "src/utils/a.js", "target": "src/utils/b.js" },
      { "source": "src/utils/b.js", "target": "src/utils/c.js" },
      { "source": "src/utils/c.js", "target": "src/utils/a.js" }
    ],
    "label": "Cycle: src/utils/a.js → src/utils/b.js → src/utils/c.js"
  }
]

Cycle Visualization

After running detect, open graph.html (via codebase-vis serve or directly) and click the cycle toggle button. Cyclic edges are highlighted in red, and non-cyclic nodes dim. Click individual cycles to zoom in.

Flags

Flag	Description
(none)	No flags — just run codebase-vis detect

Notes

• Run codebase-vis generate first — detect reads from the existing graph.json
• The 200-cycle cap prevents the command from overwhelming the terminal on deeply entangled codebases. The first 200 distinct cycles are reported.
• Entity nodes and external packages are excluded from cycle detection (they can't form meaningful cycles)
• Detected cycles are automatically visualized in graph.html via the cycle overlay feature