Skip to main content

Tutorial 3: Relationship Analysis Deep Dive

Before refactoring a service, you need to know what depends on it, what it depends on, and what would break if you changed its interface. This tutorial walks through ciak analyze-relationships — from a quick dependency check to a full architectural audit.

What you'll use: ciak analyze-relationships

Time: ~20 minutes

Prerequisite: A scanned project. Run ciak scan first if you haven't already.

Step 1 — Quick dependency check​

Start with the fastest mode to get an immediate picture of direct dependencies:

ciak analyze-relationships AuthService --mode quick

This runs at depth 1 — only immediate dependencies and dependents, no pattern detection, no quality metrics. It's the right choice when you just want a fast answer.

Sample output:

🔍 Starting relationship analysis...
  Target: AuthService
  Mode: Quick

════════════════════════════════════════════════════════════════════════════════
  Relationship Analysis: AuthService
════════════════════════════════════════════════════════════════════════════════

📊 Graph Summary
  Total relationships: 8
  Direct dependencies: 3
  Direct dependents: 4
  Inheritance chain: 1
  Interface implementations: 1
  Data flow relationships: 2
  Module coupling: 2

⏱️  Performance Summary
  Total Duration: 42ms
  Graph Building: 38ms

In under 50ms you know: AuthService has 3 things it depends on and 4 things that depend on it.

Step 2 — Standard analysis with quality metrics​

The default standard mode (depth 2) adds quality metrics, impact analysis, and call chain analysis:

ciak analyze-relationships AuthService --show-quality --show-impact --show-call-chains

Quality metrics​

📈 Quality Metrics
  Coupling Score: 0.42 ✓
  Cohesion Score: 0.71 ✓
  Stability Index: 0.58
  Abstractness: 0.25
  Maintainability Index: 74.3
  • Coupling Score — how tightly this symbol is bound to others (lower is better; above 0.7 is a warning)
  • Cohesion Score — how focused the symbol's responsibilities are (higher is better; below 0.3 is a warning)
  • Maintainability Index — a composite score (0–100); above 65 is generally healthy

Impact analysis​

💥 Impact Analysis
  Direct Impact: 4 symbols
  Indirect Impact: 11 symbols
  Impact Score: 0.68

  Directly Affected:
    • AuthController
    • JwtStrategy
    • SessionService
    • AppModule

This tells you: if you change AuthService's interface, 4 symbols are directly affected and 11 more are indirectly affected. An impact score of 0.68 means this is a high-impact symbol — changes here ripple widely.

Call chain analysis​

📞 Call Chain Analysis
  Average Chain Length: 3.2

  Longest Chains:
    1. AppBootstrap → AppModule → AuthModule → AuthService (length: 4)
    2. AuthController → AuthService → UsersService (length: 3)
    3. JwtStrategy → AuthService → JwtService (length: 3)

Call chains show you the execution paths that flow through this symbol — useful for understanding how a request reaches it and what it triggers downstream.

Step 3 — Detect circular dependencies​

Circular dependencies are always checked, regardless of mode. Run a standard analysis and look for the cycles section:

ciak analyze-relationships PaymentModule --show-cycles

If cycles exist:

🔄 Circular Dependencies
  ⚠ 2 cycle(s) detected
  1. PaymentModule → OrderModule → PaymentModule
  2. PaymentService → NotificationService → PaymentService

If none:

🔄 Circular Dependencies
  ✓ No circular dependencies detected

Step 4 — Detect architectural patterns​

Pattern detection runs in deep mode (depth 3) and above. It identifies well-known design patterns in your code:

ciak analyze-relationships UserRepository --mode deep --show-patterns --show-quality
🎨 Architectural Patterns
  • Repository (confidence: 94.2%)
    Implements data access abstraction with CRUD operations
  • Strategy (confidence: 78.5%)
    Multiple interchangeable implementations detected
  • Observer (confidence: 61.0%)
    Event emission pattern detected in dependents

Each pattern comes with a confidence score. High-confidence detections (above 80%) are reliable; lower scores are hints worth investigating manually.

Step 5 — Visualize the dependency graph​

Add --show-visualization to render the graph. Choose the format that fits your workflow.

ASCII tree (best for terminal reading)​

ciak analyze-relationships AuthService \
  --show-visualization \
  --viz-format ascii
🎨 Visualization
AuthService
├── [depends on]
│   ├── UsersService
│   ├── JwtService
│   └── ConfigService
└── [depended on by]
    ├── AuthController
    ├── JwtStrategy
    ├── SessionService
    └── AppModule

Mermaid diagram (paste into any Mermaid renderer)​

ciak analyze-relationships AuthService \
  --show-visualization \
  --viz-format mermaid
flowchart TD
    AuthService --> UsersService
    AuthService --> JwtService
    AuthService --> ConfigService
    AuthController --> AuthService
    JwtStrategy --> AuthService
    SessionService --> AuthService
    AppModule --> AuthService

Paste this into mermaid.live or any Markdown editor that supports Mermaid to get a rendered diagram.

Graphviz DOT (for custom rendering)​

ciak analyze-relationships AuthService \
  --show-visualization \
  --viz-format dot \
  --viz-layout hierarchical

Pipe the output directly to dot to generate an image:

ciak analyze-relationships AuthService \
  --show-visualization \
  --viz-format dot \
  | dot -Tpng -o auth-service-deps.png

Step 6 — Analyze a file instead of a symbol​

You can pass a file path instead of a symbol name. CIAK will analyze the primary class or interface in that file:

ciak analyze-relationships src/auth/auth.service.ts \
  --show-quality \
  --show-impact

This is useful when you know the file but not the exact class name.

Step 7 — Save results to a file​

For large analyses or sharing with your team, save the output as JSON or YAML:

# Save as JSON
ciak analyze-relationships AuthService \
  --mode deep \
  --show-patterns \
  --show-quality \
  --show-impact \
  --output json \
  --output-file auth-analysis.json

# Save as YAML
ciak analyze-relationships AuthService \
  --output yaml \
  --output-file auth-analysis.yaml

The JSON output includes the full graph, all metrics, patterns, call chains, and performance data — useful for scripting or CI checks.

Step 8 — Performance tuning for large codebases​

On large projects, deep or critical modes can be slow. Use these flags to keep analysis fast:

ciak analyze-relationships LargeService \
  --mode standard \
  --max-nodes 100 \
  --call-chain-max-depth 2 \
  --call-chain-max-paths 5 \
  --timeout 20
FlagWhat it controlsWhen to lower it
--max-nodesTotal BFS nodes collectedGraph is very large
--call-chain-max-depthHow deep call chains are tracedCall chains time out
--call-chain-max-pathsHow many call paths are collectedToo many paths returned
--timeoutHard timeout in secondsPrevent runaway analysis

For a quick sanity check on a large symbol, --mode quick --max-nodes 30 is the fastest option.

Step 9 — Enable source context for richer output​

By default, CIAK doesn't fetch the source code snippet for each dependency node (it would require one database query per node). Enable it when you want richer output on a small graph:

ciak analyze-relationships AuthService \
  --mode quick \
  --fetch-source-context

Each dependency node in the result will now include the actual code snippet, not just the symbol name and file path.

Choosing the right mode​

GoalRecommended command
Quick dependency check--mode quick
Pre-refactor impact assessment--mode standard --show-impact --show-call-chains
Architectural review--mode deep --show-patterns --show-quality
Full audit, save results--mode deep --show-patterns --show-quality --show-impact --output json --output-file report.json
Large codebase, fast check--mode quick --max-nodes 50 --timeout 15

What you've learned​

  • How to run a quick dependency check with --mode quick
  • How to read quality metrics (coupling, cohesion, maintainability)
  • How to use impact analysis to understand the blast radius of a change
  • How to detect circular dependencies
  • How to detect architectural patterns with --mode deep
  • How to visualize the dependency graph in ASCII, Mermaid, or DOT format
  • How to tune performance for large codebases