Skip to main content

What is analyze-relationships?

The analyze-relationships command performs a deeper structural analysis than related-files. It can build dependency graphs, detect cycles, estimate change impact, calculate quality metrics, and generate visualizations.

ciak analyze-relationships [OPTIONS] <TARGET>

Where you see it in the product​

  • CLI — detailed relationship analysis and dependency visualization from the terminal.
  • MCP — the analyze_relationships MCP tool exposes the same analysis capabilities to AI assistants.

Behavior and options​

Core arguments​

OptionDescription
<TARGET>Symbol name or file path to analyze (required, positional)
-m, --mode <MODE>Analysis mode: quick, standard (default), deep, critical
-d, --max-depth <N>Override traversal depth (1–20)
--include-testsInclude test files in the graph
--max-nodes <N>Hard cap on returned graph participants/relationships after filters are applied
--include-builtinsInclude builtin and standard-library relationships
--exclude-builtinsExclude builtin and standard-library relationships
--edge-types <LIST>Restrict output to import, call, inheritance, member_use, type_reference
--only-critical-chainReturn compact target-centric call-chain output for route tracing
--exclude-synthetic-nodesSuppress synthetic utility artifacts (for example map, push, log)
-t, --timeout <SECONDS>Timeout for analysis
--no-cacheDisable cached results

Output controls​

OptionDescription
-o, --output-file <FILE>Write results to a file
--show-patternsShow detected architectural patterns
--show-qualityShow quality metrics (coupling, cohesion, maintainability)
--show-impactShow impact / blast-radius analysis
--show-cyclesShow circular dependencies
--show-call-chainsShow call chain analysis
--show-filter-diagnosticsShow filter/exclusion diagnostics summary and sampled examples
--show-visualizationPrint a graph visualization

Visualization options​

OptionDescription
--viz-format <FORMAT>mermaid, dot, ascii, or json
--viz-layout <LAYOUT>DOT layout strategy (for DOT output)
--viz-theme <THEME>Visualization theme (for supported formats)
--mermaid-diagram-type <TYPE>Mermaid diagram type (flowchart, class, sequence)

When to use it​

  • Before refactoring a central service or module.
  • To estimate blast radius before changing a widely used symbol.
  • To investigate circular dependencies or architecture drift.
  • To generate a visual dependency graph for code reviews and design discussions.

Examples​

Example 1 — Standard analysis for a file​

ciak analyze-relationships "src/auth/service.ts"

Example 2 — Deep analysis with quality + impact insights​

ciak analyze-relationships "AuthService" \
  --mode deep \
  --show-quality \
  --show-impact \
  --show-cycles

Example 3 — Mermaid visualization​

ciak analyze-relationships "authenticate" \
  --mode quick \
  --show-visualization \
  --viz-format mermaid

Example 4 — Save JSON output​

ciak analyze-relationships "src/lib.rs" \
  --mode standard \
  --output-file analysis.json

Input and output examples​

Representative CLI output (truncated; exact formatting may vary by version):

Text output in terminal​

Input

ciak analyze-relationships "AuthService" --show-quality --show-impact --show-cycles

Output

Starting relationship analysis...
  Target: AuthService
  Mode: Standard

Relationship Analysis: AuthService

Graph Summary
  Total relationships: 24
  Direct dependencies: 6
  Dependents: 4

Quality Metrics
  Coupling score: 0.42
  Cohesion score: 0.81
  Maintainability index: 78

Impact Analysis
  Direct impact: 4 nodes
  Indirect impact: 11 nodes
  Impact score: 0.67

Circular Dependencies
  none detected

JSON file output​

Input

ciak analyze-relationships "AuthService" --output-file analysis.json

Output

✓ Results written to: analysis.json

analysis.json (partial):

{
  "target": "AuthService",
  "graph": {
    "direct_dependencies": [
      { "name": "UserRepository", "relationship": "uses" }
    ],
    "dependents": [
      { "name": "AuthController", "relationship": "uses" }
    ]
  },
  "quality_metrics": {
    "coupling_score": 0.42,
    "cohesion_score": 0.81,
    "maintainability_index": 78
  },
  "impact_analysis": {
    "impact_score": 0.67
  },
  "cap_metadata": {
    "cap_requested": 50,
    "cap_applied": 50,
    "cap_reached": false,
    "dropped_node_count": 0
  },
  "filter_diagnostics": {
    "filters_applied": ["tests", "builtins"],
    "excluded_count": 5,
    "exclusion_buckets": {
      "tests": 2,
      "builtins": 3,
      "synthetic": 0,
      "edge_type_mismatch": 0,
      "depth_pruned": 0,
      "cap_pruned": 0
    },
    "returned_size": {
      "nodes_before_filter": 24,
      "nodes_after_filter": 19,
      "nodes_returned": 19
    }
  }
}

cap_metadata lets you verify that node/edge limits were enforced deterministically for the request. filter_diagnostics provides machine-readable exclusion accounting (including reason buckets and returned-size summary).

Synthetic suppression rules are loaded from language packs under src/rust/common/src/relationship_analysis/builtin_packs so new languages can be added by data-pack updates instead of hardcoded logic.