Graph Types

Graph Types

Arxo builds and analyzes multiple graph representations of your codebase. Each graph captures different architectural relationships.

Import Graph

The Import Graph represents module-level dependencies extracted from import/require statements.

What It Captures

Nodes: Files, modules, or packages (depending on grouping) Edges: Import/dependency relationships

Example

src/components/Button.tsx

import { theme } from '../styles/theme';
import { logger } from '../utils/logger';

// src/pages/Home.tsx
import { Button } from '../components/Button';

Import Graph:

pages/Home.tsx → components/Button.tsx
components/Button.tsx → styles/theme.tsx
components/Button.tsx → utils/logger.tsx

Grouping Options

Control granularity with group_by and group_depth:

File-level (default):

import_graph:
  group_by: file

Folder-level:

import_graph:
  group_by: folder
  group_depth: 1  # Group by immediate parent folder

Package-level:

import_graph:
  group_by: folder
  group_depth: 2  # Group by top-level packages

Use Cases

• Detect circular dependencies (SCC metric)
• Measure propagation cost
• Identify architectural layers
• Validate import rules

---

Call Graph

The Call Graph represents function and method invocations.

What It Captures

Nodes: Functions, methods, classes Edges: Function calls, method invocations

Example

utils/logger.ts

export function log(message: string) {
  console.log(message);
}

// services/api.ts
import { log } from '../utils/logger';

export async function fetchData(url: string) {
  log(`Fetching ${url}`);
  return fetch(url);
}

// components/DataLoader.tsx
import { fetchData } from '../services/api';

export function DataLoader() {
  const data = fetchData('/api/data');
  // ...
}

Call Graph:

DataLoader() → fetchData()
fetchData() → log()
fetchData() → fetch()

Cross-Language Calls

Arxo tracks calls across language boundaries:

TypeScript → Python (via REST API):

frontend/api.ts

fetch('/api/analyze')

// backend/main.py
@app.route('/api/analyze')
def analyze():
    return run_analysis()

Use Cases

• Analyze runtime dependencies
• Find unused functions
• Detect code smells (God functions)
• Impact analysis for changes

---

Entity Graph

The Entity Graph represents high-level component relationships.

What It Captures

Nodes: Files, modules, components Edges: Various relationships (imports, calls, shared types)

Example

In a React application:

Feature/Auth → Component/LoginForm
Feature/Auth → Service/AuthAPI
Service/AuthAPI → Util/Http
Component/LoginForm → Util/Validation

Use Cases

• High-level architecture visualization
• Component boundaries
• Feature dependencies
• Architectural diagrams

---

Graph Metrics

Each graph enables different metrics:

Import Graph Metrics

Metric	What It Measures
SCC	Circular dependencies
Propagation Cost	Change impact
Modularity	Community structure
Hierarchy	Layer violations

Call Graph Metrics

Metric	What It Measures
Call Depth	Nesting complexity
Unused Functions	Dead code
Effect Violations	Side effect boundaries
Critical Path	Most-called functions

Entity Graph Metrics

Metric	What It Measures
Centrality	Critical components
Core-Periphery	Architectural zones
Coupling	Component dependencies

---

Graph Visualization

Export Graph Data

Export graphs for visualization:

# Export import graph as GraphML
arxo analyze --format json --output report.json

# Extract graph from report
jq '.graphs.import_graph' report.json > import_graph.json

Visualization Tools

Use these tools to visualize exported graphs:

• Graphviz - DOT format rendering
• Gephi - Network analysis and visualization
• Cytoscape - Biological network visualization
• D3.js - Custom web visualizations
• Neo4j - Graph database queries

Example: Graphviz DOT

Convert Arxo output to DOT format:

import json

with open('report.json') as f:
    report = json.load(f)

import_graph = report['graphs']['import_graph']

print('digraph G {')
for node in import_graph['nodes']:
    print(f'  "{node}" [label="{node}"];')

for edge in import_graph['edges']:
    print(f'  "{edge["source"]}" -> "{edge["target"]}";')
print('}')

Render with Graphviz:

python to_dot.py | dot -Tpng -o graph.png

---

Graph Filtering

Exclude Patterns

Filter out noise:

import_graph:
  exclude:
    - "**/node_modules/**"
    - "**/test/**"
    - "**/*.test.ts"
    - "**/dist/**"

Language-Specific Filters

import_graph:
  languages:
    - typescript
    - python
  exclude:
    - "**/*.spec.ts"      # TypeScript tests
    - "**/test_*.py"      # Python tests

Size Thresholds

Limit graph size for performance:

import_graph:
  max_nodes: 10000
  max_edges: 50000

---

Advanced Topics

Graph Persistence

Graphs are cached between runs:

# Cache location (default)
~/.cache/arxo/graphs/<project-hash>/

# Disable caching
arxo analyze --no-analysis-cache

# Clear cache
arxo cache clear

Incremental Updates

When files change, Arxo:

1. Detects changed files (via git or filesystem)
2. Invalidates affected graph nodes
3. Re-parses only changed files
4. Updates graph edges
5. Recomputes affected metrics

Graph Queries

Future feature: Query graphs directly

# Find all paths from A to B
arxo graph query --from "src/A.ts" --to "src/B.ts"

# Find modules with most dependencies
arxo graph query --top-dependencies 10

---

Next Steps

• Configuration Guide - Configure graph options
• SCC Metric - Detect circular dependencies
• Propagation Cost - Measure change impact
• Centrality Metric - Find critical nodes